Copyright: © 1995 SINFIC SA. (Portugal)
Citation: Help generated by SOS Help! Info-Author


Contents


About This Help File

his file’s objectives: For starters, we aim to give you, in a simple and unassuming way, some hints on how to achieve a more interesting look to your work; we also provide the complete source for this project, so you’ll be able to play and learn a few tricks with it; and last, we explain how to create and maintain efective and elegant “glossaries of terms” to be included in your projects, speaking on the way about the use of secondary windows and others matters of interest for “help” authors.

One of the situations you are bound to face as you grow in the mastering of the craft, is the quest for further knowledge. To assist you to achieve productive and more rewarding work, we offer a directory of some of the development resources available.

Some topics, like the one before your eyes, will be particularly lengthy. To help you read through them, we've included a small topic table of contents, in a popup associated with the symbol of a down pointing arrow that you'll find in the right hand corner of the non-scrolling region. Actually, you can and probably should access this popup by clicking the mouse's right button, which calls WinHelp’s “Floating Menu”.

There are in all three symbols that will appear in some topics, in the same position. You should get used to them.  Other peculiarities are not documented, but you shouldn't have much difficulty in understanding them.

There is only one single browse sequence, which allows you a simple way of browsing through all topics that appear in the main window, from start to finish.

The “Glossaries” section expounds on our main theme. The “Baggage” section allows you to extract to disk some useful freeware or public domain templates and utilities and also offers insights on some tricks used in the making of this particular file.

That's about all. I hope you enjoy the ride.

Pedro Leite Fragoso
Rio de Mouro, January 1995


y a glossaries
Glossaries

 Why a “Glossary”?

 How to make it?

 A typical approach

 A different approach

 A complex approach

 Care with details

 Creating a proper “Index”


y a treasure chest
Baggage

 How this file was done

 WinHelp Development Resources

 Accessing the file's “baggage”


Credits

A WinHelp’s “Glossary” How To, first edition

developed by [image] CNS - Companhia Nacional de Serviços

with [image] SOS Help! Info-Author v2.1

and using dlls by José Humberto Bento and Tom Gibson

published in January of 1995 by SINFIC SA. (Portugal)

with trademark acknowledgment, a copyright message, an obligatory disclaimer and a note on system requirements


x data Virtual Media Technology
Virtual Media Technology

  Virtual Media Technology Pty Ltd.

Level 21   201 Miller Street
North Sydney, NSW 2089
Australia

Phone: +61-2-9592355
Fax: +61-2-9534044

Compuserve: 100240,2455
Internet: 100240.2455@compuserve.com


x data Lamaura Development
Lamaura Development

Lamaura Development Ltd.
Rabley Park, Ridge
Potters Bar
Hertfordshire EN6 3LX
United Kingdom

Phone:  +44-1707-643278
Fax/BBS:  +44-1707-643499

Compuserve: 100016,1254
Internet: sales@lamaura.com

    SOS Help! Info-Author


y mtjs about
Topic Contents

 Go back to the beginning

 Symbols that appear in topics

 This help file structure


y a symbols
Topic Symbols

there is a note pertaining to this topic

the topic has an internal table of contents

there are other topics related to this one

You may access the topic's “Contents” and “See Also” lists,
if they exist, either by clicking on the provided symbols, or by
way of the “Floating Menu” (right click). You may only read any
topic's “Note” by clicking on its symbol.


z template Main Window Topics
Title Here

Text here

rtf

More text here


z template Data Window Topics
Title Here

Country

Phone:

Fax/BBS:

Compuserve:

Internet:


z template Mid-Topic Jumps popup Topics
Topic Contents

 Go back to the beginning


Why a "Glossary"?
Why a “Glossary”?

sually, you should have a glossary feature in your help file or hypertext document. There are, almost as a rule, scores of terms that pertain to your work and to have them properly explained to your users/readers would improve the presentation of your work.

Popups are used for this, of course, and you may well charge your file with definitions in popups scattered around. However, there are two reasons not to overdo it: In the first place, you'll risk having a cluttered document and in the second place, your users may well search for a definition that they know is somewhere in there, but won't be able to locate, exactly when they need it the most.

The “Glossary” is a topic that includes a list of all the terms you use and come across, deserving of an explanation. Each of the terms here will be assigned a popup. Each of these popups, of course, correspond to another topic you'll have to create. The users will access this “Glossary” topic via (1) a button you'll create in the button bar, or (2) an option you'll include in the Help Menu, or (3) an accelerator key you'll assign to this action.

This way, your user will get easily to descriptions of terms and you'll be able to spare your popups.


z template popup Topics
Murphy’s Law

If anything can go wrong, it will.


y a murphy
Murphy’s Law

If anything can go wrong, it will.


y mtjs whyg
Topic Contents

  Go back to the beginning

  What’s a “Glossary”?


z template See Also popup Topics
Related Topics


y sa why a glossary
Related Topics

 How to make it?

 A typical approach

 A different approach

 A complex approach

 Care with details


A Glossary How To

he elements to bear in mind in order to get this right, are:

1. A number of topics, one for each term to be explained

a. The topic's title on the first line is the term itself

b. After the title, there's the definition or explanation

c. These topics are designed to appear as popups
(if there's a more complete explanation for the relevant word somewhere else in the help file, any jump to it should be defined inside the popup topic)

2. A topic with the “Glossary” proper

a. This topic is made to appear in a secondary window

b. Its non scrolling region has buttons with the letters of the alphabet (this may and probably should be achieved via a segmented hypergraphic)

c. Each of these letters points to a “context string” in the scrolling region of the topic; the context string is defined next to the first term that starts with the corresponding letter; actually, the letter (not as a button anymore ) should be repeated here, as a header for the section of words starting with it

d. The words themselves are all associated with topics that are made to appear as popups, when the user accesses them

3. A button in the toolbar calls the “Glossary” topic

4. An “accelerator” key also calls the Glossary

5. For completeness, an option in the Help Menu also calls the Glossary (your user won't get lost!)

You may consult and copy the code for these from the [image] Typical Approach topic.

If your Glossary is composed of just a few words, there's no need for many of the procedures discussed above: just put the words in a topic and make it appear as any other in the main window (but do give your users a simple way of getting there, via a button, etc.).

On the other hand, if you find that your Glossary is, in its extension, something of a dictionary, you may want to check  the [image] “Complicated Way” topic.


Typical Approach
A Typical Approach

n this help file, called “glossary.hlp”, the secondary window used to show the Glossary is called “sub_2” and the Glossary topic is called “glossary”.

• AddAccelerator(0x47,2,"JumpId(`glossary.hlp>sub_2',`glossary')")
is the macro statement used to assign to <Ctrl +G> the access to the Glossary

• InsertItem("mnu_help","help03","&Glossary    Ctrl+G",
 "JumpId(`glossary.hlp>sub_2',`glossary')",3)
is the macro statement used to to insert in the Help menu an item that allows the user access to the Glossary; the “Ctrl G” part is there simply as the normal Windows usage reference to the possible use of the accelerator key

• CreateButton("btn_gly","&Glossary",
"JumpId(`glossary.hlp>sub_2',`glossary')")
is the macro statement used to add a button to WinHelp’s toolbar that allows access to the Glossary.

What the user will actually see after clicking, pressing or accelerating will depend on your design of things. In the lexia on [image] Care With Details we elaborate a bit more on this subject.

Our illustration shows the typical visual approach to a “Glossary” window in a help file.


Different Approach
A (Slightly) Different Approach

here's a font approach everybody always uses for Help (for all the good reasons, by the way: it works, it's proved, it's solid): for the body of the text, a sans serif font, like MsSansSerif or Arial (or Helvetica) at 10 or 11 points, with titles bold and a little bigger.

“Sans serif fonts” are arguably more readable that the “serif” ones, like TimesNewRoman. If you decide to go for one of these, you should use at least 14 points.

You may use secondary windows as an alternative to these rules, so underlining its intended specific use and making the reading experience more interesting. Just don't forget that things should be kept aesthetically readable.

One of the myriad aspects that distinguishes writing for the screen as opposed to paper is the greater possibility of using colours. Once again, when in doubt you ought to be conservative. Being conservative always works, whilst  pretending to be creative with such things as colours may give appalling results.

In our [image] “Glossary”, there are different tones of grey for the backgrounds of the scrolling and non-scrolling regions, the section header letters are set at TimesNewRoman, bold, 18 points, in white and the terms are set at dark red. There is no linking information pertaining to these words (ie, the ubiquitous WinHelp green underline or our own approaches elsewhere in this document), because it has to be obvious that the only reason they are there is to offer information!

Or so we think...

Give some attention to the size and positioning of the secondary window. If the term explanations are longer rather than shorter, you'll may need to have a wider window. The size WinHelp gives to popups depends ultimately on the size of the original window: if this is short, the text inside the popup may well be unceremoniously cropped.

One way of possibly avoiding this effect is to have the text of the popup topics inside (one column) tables. Anyway, you should bare it in mind.


y sa index
Related Topics

 Why a “Glossary”?

 How to make it?

 A typical approach

 A different approach

 A complex approach

 Care with details

 Books on indexing


A Proper Index

he “Search” engine of Windows 3.1 Help is a basic approach to an Index — if you compare the best indexes in your favourite technical books with what you can accomplish with WinHelp’s Search engine, you will be disappointed.

You'll also risk disappointment with your efforts, because creating a good Index is not nearly as easy as it may seem. Don’t deceive yourself, a good Index is born out of craft and profession.  Read the [image] recommended books.

Nevertheless, if you wish or need to include a true to form Index in a help file (not the case here, fortunately), you can use most of what you may learn around this little web, only instead of calling up topics in popups, the index keys in the purported “Index” window should cause jumps to the appropriate topic in the [image] right windows.

A rare example of a well known help file with a book-like index is Microsoft’s Word for Windows v6.

A small note here: There are of course ways of providing any help file with [image] powerful full text search capabilities. These are nice to have available (and since they are an automatic way of doing things, they are cheap to implement), but do not replace in any way the convenience and extreme usefulness of a well crafted “conceptual” index. Sorry, but we don’t have space to discuss this subject further.


How This Help File Was Done

aving been developed within a wysiwyg authoring environment, the look&feel of the final help system was always present during every little step of the development of this document. To be able to work in a wysiwyg environment is truly a luxury you should, at the very least, experience — be advised, you'll feel compelled to add it to your toolbox.

In terms of development strategy, we tried to follow every piece of advice from the book by [image] Boggan, Farkas and Wellinske. Since this book is essential reading for any help author that’s serious about what he’s doing, we’ll just assume in the next paragraphs that you are fully aware of the lessons in there.

In a “genuine” hypertext authoring environment, your work is built on the lexias themselves, each one of them having a separate identity. To have and maintain coherence, topics  in a help system obey sets of rules: in this case, we had different approaches for topics that appear (a) in the main window, (b) as popups, (c) in the secondary “Data Window” and (d) in the Glossary, which was a special case. So, after structuring the contents, we created one or two topics for each of these cases, to obtain an initial feel of the work. This over, we fleshed out one of each of these topics and saved them to be used as templates for any others that would be done similarly.

 The look of the file was created specifically to it, based on a very soft “style sheet” we use in commercial projects. If you are a SOS Help! Info-Author user, you’ll also be able to use or adapt it, if you wish. It's available from the [image] “baggage” of this file.

One of the many problems (work overload, ego, irritating minutiae, etc.) of working with a graphic designer is that he’ll kill to get the look he’s after. Ours (a Mac user and fan who’s always complaining about having to do work for PCs) just couldn’t accept what the absolute co-ordinates scheme of WinHelp would do to his work. So, we were more or less forced to develop a dll that would account for the different user resolutions. This has meanwhile become a part of the [image] Small Touches for WinHelp suite.

We've also used, from the same suite, macros that allow flexible printing of the help file topics and a few others: for instance, if you opened this file by clicking on its icon in Program Manager or its name in File Manager, you’ll get our icon when alt-tabbing, not WinHelp’s; the opening splash screen was another feature; as was the “extractable from baggage” feature; we’ve also accomplished the topic by topic use of the floating menu, thanks to an extra ability to run macros on topic exit. Please, note that these last 4 functions are included in helputil2.dll, the copyrighted component of Small Touches (if you’d like to run macros on topic exit, but don’t wish to license this, you may use macros from Ron Loewy’s [image] Interactive Help for Windows or Ron Burk’s free [image] HelpTools).

Finally, the 3D look of the dialogs was achieved with Tom Gibson’s very clever wh3d.dll, a public domain piece whose documentation you can also extract from this file’s [image] baggage (the dll itself was installed during setup). The 3d dialog boxes may seem nice to you, but try to convince a laptop user!

Since you can extract the project files from [image] baggage, it will be easy to study and uncover any details left explained. If you are a SOS Help! Info-Author user, you have a SHP of the project (plus the bitmaps, of course), so you’ll be able to automatically rebuild the whole thing.


Accessing The File's Baggage
From The “Baggage”

ere’s the key to our trunk. We've included project “templates” and two public domain and freeware utilities that’ll help you develop WinHelp files. Just choose from the baggage and extract to your disk.

 wh-gly.zip

SOS Help! Info-Author project file (“wh-gly.shp”) plus bitmap and segmented hypergraphic for a ready to use glossary of WinHelp related terms; a few things may not be obvious, so you’ll have to tinker with it for a while, before puting it to use; to actually import this into an existent project, you’ll probably have to first export it to a “.sht” (S4W text) file; the style sheet used can be found next; the original project directory was c:\projects\glossary.

 stysheet.zip

an archive of this file’s style sheet, for SOS Help! Info-Author users; it isn’t documented, so you’ll need to explore things out.

 source files

“glossary.hlp” project files: .shp, .bmp, .hpj and .rtf files; with these, you should be able to rebuild and study this project inside of any authoring environment; the original project (.hlp, .hpj, .ico, .dll, baggage files) directory was “d:\projects\glossary\hlp”, the .rtf files directory was “d:\projects\glossary\rtffiles” and the bitmap (.bmp and .shg referenced files) directory was “d:\projects\glossary\bmp”.

 wh3d.hlp

documentation for Tom Gibson’s 3d dialog boxes dll, used in this help file; since you have the dll itself from the setup procedure, it isn’t included in the baggage; you can find an introduction to this program in the [image] More DLLs lexia.

 shgrez.zip

you can find an introduction to this Visual Basic application (you’ll need vbrun300.dll, not packed) in the [image] Essential Utilities lexia.

 hypershelf specific files

if you are a [image] Hypershelf user, “glossary.inx” will add a structured Table of Contents to this help file, so you won’t need to create it yourself (the full text search file is included in “glossary.fts”; you need to add these files to the directory where you installed “glossary.hlp”). We’ve actually made this document particularly Hypershelf aware: there are some “structuring” topics in the hypertext that will only be of use to Hypershelf users (and so, most of these will only be available to them — although some of these topics appear in the main browse sequence and during printing) and allow a second, quite different perspective of this work. You may consult the topic on [image] the Hypershelf version for a further presentation of this approach.


WinHelp Development Resources

eginning WinHelp authors have the same basic, classical questions: what, where, how? Even if this business of WinHelp file development still represents a relatively small market niche, a crop of remarkable different resources seems to keep appearing at an astonishing rate.

We offer some data on a few of these resources, such as [image] available books and other paper based documentation, [image] electronic texts in help file format and a [image] few readily accessible examples and samples; we also give out information on some of the [image] online sources that will keep you abreast of the news and let you download files; and also [image] two professional organisations that may be of interest; we write about some of the [image] dlls and programs available to extend the power and viability of the Windows Help engine; and we round things up with a mention of [image] essential and [image] general development utilities which you shouldn’t be without.


y sa about
Related Topics

 How This Help File Was Done

 WinHelp Development Resources

 Accessing The File’s Baggage


y mtjs a glossary how to
Topic Contents

 Go back to the beginning

 The “Glossary” topic

 Making the user get to the Glossary

 Easier and harder ways


y sa a glossary how to
Related Topics

 Why a “Glossary”?

 A typical approach

 A different approach

 A complex approach

 Care with details

 Accessing the file's baggage


y nota glossary how to
Nota Bene

In the [image] “Baggage” section of this file, there's an option that
allows you to extract to disk SOS Help! Info-Author ready
templates that may be used to ease the creation of a
“Glossary” such as described here.

The corresponding HPJ and RTF will also be extracted.

These are ready to be imported into any of your projects, allowing
you an adequate degree of automation in its creation.

However, be advised that you have everything to gain by knowing
how to do it from scratch.


y g term
term

A word having a precise meaning, esp.one that is peculiar to a particular group or activity: a medical term.

in Microsoft Bookshelf, © 1987 - 1992 Microsoft Corporation.


The Complicated Way
A More Complex Approach

o, you are way past needing a Glossary. You are after a Dictionary.  You might consider having one topic for each letter (sorry, we won’t be considering more elaborate alternatives than this), either in a secondary window or in the main window.

Our normal button setup would be poor. You can create a “cover page” for the Glossary, with buttons like this:

in Microsoft Bookshelf,
© 1987 - 1992 Microsoft Corporation.

Say the user would choose letter “L” (try it). He would go to the topic with all the terms that start by “L”. The button setup there would give the impression of an actual pressed button. Of course, you'd have to design a different bitmap for each topic. Lots of work.


Being Careful With The Details
The Care With Details

ifferent colours, bitmaps, secondary windows: life starts getting messy and time gets shorter. Some words of advice about possible quirks:

1. On using bitmaps
You need to match the “background” colour of any bitmap you may use with the background colour of your help system; now, If you are using the same bitmap in a topic that will appear in the main and in a different background coloured secondary window, you'll probably need two topics! This alone usually proves reason enough for leaving black on white.

2. On window sizes
If you are serious about a “nice” visual approach to your work, you'll get frustrated by WinHelp’s absolute co-ordinates of 1024x1024, regardless of screen resolution. After all, the thing was created to do help files, not multimedia works of art! What looks good at one resolution may not work at all at another. Test your system and be conservative. You may wish to use a dll such as winsize2.dll — a part of the [image] Small Touches for WinHelp suite that was placed in the public domain (so, it's free) —, that allows you to take into account your user's actual screen resolutions.

3. On jumps inside secondary windows
By default, a jump from a topic that happens to be in a secondary window will make the inbound topic appear in the original secondary window. You'll have to specifically direct the jump to the main window, if you wish it so. You'll have to take this into account in the case of possible jumps from inside topics that'll appear as popups in the Glossary.

4. On global glossaries
If you have several files with the same general subject, you should consider a global glossary. Make the glossary apart and import or include it into each of your projects. Have care with the consistency of styles used.

By the way, yes we could have added a bitmap as button for “Close” purposes in the Glossary secondary window, as we've done for most of the other secondary windows — but is it really neccessary? The bitmap cap used at the beginning of each topic looks good (and could have been made into a drop cap, of course), but won't be copied or printed. We are aware of that (if one wants to make proper use of bitmaps, one really needs to include [image] ShowBMP in the bag of utilities). Also, remember that instead of just one bitmap with all the letters in the non-scrolling region of the “Glossary” topic, you might want to have [image] one bitmap for each letter. This way, the resizing of the “Glossary” window wouldn't be so hard on your users (of course, we ourselves would have it harder, if we could...)


x Glossary
A - D

accelerator keys

aleph

context strings

dll

E - H

hypermedia

hypertext

I - L

jump

lexia

M - P

mid-topic jumps

navigation

pixels

popup

Q - T

secondary window

segmented hypergraphic

term

U - Z

there are no terms defined in this interval


y nota glossary
there are no terms defined in this interval


Glossary

his topic allows you to jump to the [image] Glossary.

This could be made  into a “dummy” topic, with Back(); JumpId("glossary.hlp>sub_2", "glossary") as its macros, where “glossary.hlp” is this help file's  name, “glossary” is the name of the topic that includes the actual Glossary and “sub_2” is the name of the secondary window where it will be shown. This is a trick used to allow jumps to a secondary window from the Search dialog. The topic to be shown in the secondary window would have FocusWindow("sub_2") as a topic macro. Dummy topics should’t be included in any browse sequence.

An alternative to using dummy topics could be to code the following as the “Glossary” topic macros: IfThenElse (Not(IsMark("m1")), "SaveMark(`m1'); Back(); JI(`glossary.hlp>sub_2', `glossary')", "DeleteMark(`m1')"); FocusWindow("sub_2"). Just be careful about the topic macros you are using in the other topics. Instead of Back() it’s probably safer to use a JumpId to the contents topic or any other topic that is appropriate.

We're not using any of these because they aren’t compatible with other devices we are using here. These considerations were included here just as a matter of curiosity.


y a thanks
A note of thanks

I just want to use this chance to thank some people that helped me learn whatever it is that I know about doing on-line docs (in  fact, if I was to be exhaustive, you'd soon start to wonder who didn't help).

Most things I've learned about this métier, I've learned on-line. My school, in no small measure, has been the WinHelp section of Microsoft's WinSDK forum, on Compuserve. Some people, whom I've never met personally, of course, have taught me a lot, indirectly and directly: amongst many others, Mary M. Deaton, Michael Malcolm Andersen, George Calvert, Pete Davis, Jim Mischel, Steve Pruitt, Paul O’Rear and William Meisheid.

Anything that's good about this file can easily be credited to their lessons, suggestions or comments (everything wrong and stupid is the fault of my own ill-considered choices).

Bless them all.

Pedro Leite Fragoso


x data SOS Help! Info-Author
SOS Help! Info-Author

SOS Help! Info-Author (ocasionally referred to as SOS Help! in here) provides a totally WYSIWYG, “natural” authoring environment for the creation of WinHelp ready help files and hypertext documents.

Creating hypertext documents with SOS Help! Info-Author is easy, fast and pleasurable.  Its line of features is very generous, including style sheets, easy assignment of links and compiling as fast and efficient as one could ask for. Authors won’t have to worry about cryptic codes or the intricacies of HPJ and RTF files, unless they love them.

SOS Help! Info-Author SRP is GBP £195 or USD $275. More information is available either from [image] Lamaura’s international offices in the UK or from [image] SINFIC, in Portugal.


y a trademark
Trademark and Copyright Acknowledgement

• SOS Help! Info-Author and SOS Help! are trademarks, and
Lamaura is a registered trademark, of Lamaura Development Limited.

• Hypershelf is a trademark of Virtual Media Technology Pty Ltd.

• Microsoft is a registered trademark and Windows is a trademark of
Microsoft Corporation.

• Last time we heard, WinHelp was on its way to becoming a
trademark of Blue Sky Software Corporation!

• Small Touches for WinHelp is © SINFIC SA.

Other brand and/or product names are used for identification purposes
only and are trademarks, registered trademarks or copyrights of their
respective owners.


y a copyright
© 1995 SINFIC SA.

This help file is a freeware package.  Although SINFIC - Sistemas de Informação Industriais e Consultoria SA. retains all rights to this document and its source, you are allowed to copy and distribute verbatim copies of them, as you received them, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this license and to the absence of any warranty; and distribute a copy of this license along with it. You are expressly not allowed to sell or license this package.

You may freely use any aspect of the “look&feel” of this document.

A part of this help system is not freeware or public domain. There are four dlls being used here: Tom Gibson's public domain wh3d.dll and José Humberto's 3 dlls from the Small Touches for WinHelp suite. Of these, winsize2.dll and printall.dll are in the public domain, but hlputil2.dll is © [image] SINFIC SA. You are expressly not allowed to use any of its functions in your own projects, unless you are a registered user.


x data CNS - Companhia Nacional de Serviços
CNS

Companhia Nacional de Serviços, SA.

Rua Cidade de Rabat, 29B • P-1500 LISBOA

Portugal

Phone: +351-1-7740456 • Fax: +351-1-7740667

Compuserve: 100273,310

Internet: 100272.310@compuserve.com

CNS is Portugal’s most prestigious Professional Training corporation. The company provides WinHelp based training materials and electronic documentation services, for European and other international customers.


x data SINFIC - Small Touches for WinHelp
Small Touches for WinHelp

  Sistemas de Informação
  Industriais e Consultoria SA.

Rua dos Soeiros, 311 R/C • P-1500 LISBOA

Portugal

Phone: +351-1-7274132 • Fax: +351-1-7274027

Compuserve: 100447,3652

Internet: 100447.3652@compuserve.com

Small Touches for WinHelp will be available March/April 1995, at USD 35 (the public domain components will be made available for download from Compuserve and the Internet).


y a disclaimer
Disclaimer of  Warranty

We don't believe that this help system includes anything capable of messing up your system. However, be advised that there is no warranty attached: because this help system is licensed free of charge, there is no warranty, to the extent permitted by applicable law; this is provided "as is", without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose; the entire risk as to the quality and performance of the contents of this system is with you;  should this prove defective, you assume the cost of all necessary servicing, repair or correction; in no event, unless required by applicable law or agreed to in writing, will any copyright holder, or any other party who may modify and/or redistribute this document and its source, as permitted in the license, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use the library (including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the dlls to operate with any other software), even if such holder or other party has been advised of the possibility of such damages.


y a systems requirements
System Requirements

(This is not your typical system requirements note.)

Any software package always comes with system requirements. An electronic document isn't very different. This whole system was conceived to achieve a certain “look&feel”, which you may well trash and destroy without realizing it.

If you want to consult this properly (ie, as it was conceived to be appreciated), please, don't use any “large fonts” setup option. It will probably turn out awful. Also, don't impose any special colour in the WinHelp section of you WIN.INI file. Be sure to have Arial, Times New Roman and MS Sans Serif (all of them fonts that come with Windows) duly installed! Finally, let the windows stay as they appear. They’ll stubbornly go back to their original position and sizes anyway. If you don't expect this, you’ll get unnecessarily annoyed.

The options available to you to configure your system are less limited every passing day. That may be good for you, but becomes impossible to manage for authors who wish to make any aesthetical statement. So, we have to assume certain things. We can only apologize if your system doesn't conform to our assumptions.


y g lexia
topics or lexias?

Any class of professionals will eventually develop a set of terms that become their jargon and sets them apart. People in academia are experts in this. In the “hypertext” authoring club, “lexia” should be a serious candidate to replace “topic”, because it has a more specific meaning than “topic”. It was firstly used by French author and philosopher Roland Barthes, in his search for the “perfect” text: “Hypertext denotes text composed of blocks of text — what Barthes terms a lexia — and the electronic links that join them.”

the citation is from Hypertext, a book by George Landow, © 1992 John Hopkins University Press


y g hypertext
hypertext

An American word, coined by Theodor H. Nelson in the 60s: “By hypertext, I mean nonsequential writing — text that branches and allows choices to the reader, best read at an interactive screen. As popularly conceived, this is a series of text chuncks connected by links which offer the reader different pathways”.

Of course, it needs not be only limited to text. And it may actually be put in a more radical way. Roland Barthes: “In this ideal text, the networks are many and interact, without any one of them being able to surpass the rest; this text is a galaxy of signifiers, not a structure of signifieds; it has no beginning; it is reversible; we gain access to it by several entrances, none of which can be authoritatively declared to be the main one; the code it mobilizes extends as far as the eye can reach, they are indeterminable...”

So, the Internet’s WWW is a good example of “hypertext”. WinHelp based work is just electronic documents using some hypertext principles and technology. Of course, in the end it all depends on your point of view.

citations from Hypertext, a book by George Landow, © 1992 John Hopkins University Press


y g hypermedia
hypermedia

Normally, hypertext + multimedia elements (images, sound, animations, video, etc.).

Better: “Hypermedia is concerned with the design and use of systems which support the creation, management and distribution of multidimensional webs of multimedia information”.

More: “These provide flexible access, navigation and information modelling through interaction and ‘trail blazing’. The stuff of such systems will be multimedia objects — composites which will be organised into structures for representation and communication. The real challenges for distributed information systems and hypermedia are usability, scalability, portability and interoperability.”

citations from The Role of Objects in Multimedia, an article by Peter Ward in the Summer 1994 edition of Objects in Europe, © 1994 SIGS Publications


y g aleph
aleph

You may consider using “aleph” in place of “link” in a conversation, to obscure things a bit, but be advised, it is far-fetched. “Aleph” is the creation of Latin American literary icon Jorge Luis Borges: “In that single gigantic instant I saw millions of acts both delightful and awful; not one of them amazed me more that the fact that all of them occupied the same point in space, without overlapping or transparency. What my eyes beheld was simultaneous, but what I shall now write down will be successive, because language is successive (...) The Aleph’s diameter was probably little more than an inch, but all space was there, actual and undiminished. Each thing (a mirror's face, let us say) was infinite, since I saw it from every angle of the universe”.

citation from Hypertext, a book by George Landow, © 1992 John Hopkins University Press


y g accelerator keys
accelerator keys

Sequences of keys, generally starting with <Ctrl>, <Shift> or <Alt>, associated with macros that allow the user easier or faster accomplishment of certain tasks.

In the HAG and the book by Boggan, Farkas and Wellinske, you may consult a complete list of the keys available to you, as a help author.

If you wish to read more information, you should access the several WinHelp Development Resources lexias.


x data JASC
JASC

JASC, Inc.
10901 Red Circle Drive
Suite 340
Minnetonka, MN 55343
United States of America

Phone: +1-612-9309171

Fax: +1-612-9309172

Compuserve: 72557,256

Internet: 72557.256@compuserve.com

Publishers of Paint Shop Pro and JASC Media Center.


x quote 256 Colour Segmented Hypergraphics
256 colour graphics sans dll

I have been told that you can only use 256-color bitmaps by using embedded windows and commercial DLL functions... this is NOT true.  Here's how you do it:

1. Copy your true 256-color bitmap to the clipboard;

2. Paste this bitmap into WfW2's Draw program for one nano-second;

3. Cut this back to the clipboard;

4. Paste this new WfW2 .WMF (.BMP version) into the SHED.EXE editor;

5. Add your hotspots to this new 256-color SHED.EXE rendering;

6. Enjoy your new 256-color .SHG splash screen... with hotspots... without embedded windows and without commercial DLL-support.

Most people think I must be mistaken... the help compiler WILL NOT support 256-color bitmaps... I have my original 256-color bitmap and my new .HLP file with a 256-color .SHG splash screen, but they still think I am wrong.  They say that WfW2 has converted the 256-color bitmap to 16-color and I am missing the boat. If I can use any 256-color bitmap as a 256-color .SHG with hotspots and without embedded windows and DLLs, I can use any 256-color bitmap as a 256-color .SHG...

I always hated 256-color embedded bitmaps because I need my .SHGs... end of story.

by Bruce C. Hartford

from a message posted to the WinHelp/Tools message section of Compuserve’s WinSDK forum; November 19, 1994; © 1994 Compuserve Incorporated

Comments:

• as a rule, you’ll get better and more consistent results if you do use an adequate dll;

• you can have 256 colour, dll-supported segmented hypergraphics, with a few twists of their own — use [image] ShowBMP;

• you don’t need Word for Windows v2.0 to make this work; try [image] Paint Shop Pro or any graphics package that exports “.wmf” files (Word for Windows v6.0 doesn’t work);

• if you really won’t use a dll, note that even if your 256 colour graphic isn’t intended to be a real segmented hypergraphic, you need not worry: don’t mark any hotspots in step 5. above and use the picture as it is — it will be just as fine (even if it isn’t as fine as you’d expect).


x quote Great Looking Tables
Great looking tables

or “An Even Better Way (Creating great looking tables in WinHelp”)

Yesterday I posted my musings on how to prepare tables for WinHelp files which include complex borders, shading, different colors, etc.  Other criteria are that the table must look good for all video resolutions, and not greatly add to the compile time and final WinHelp size.  Thus, bitmaps were out (even if MRBC is used).

It turned out I was close, but keeper@netcom.com, and a couple of other people, suggested a slightly different approach which works even better -- it is simpler and doesn't require anything other than Word for Windows (version 6, don't know if version 2 works for this) and SHED (the Hotspot editor).  Here's what I found:

1. In Word for Windows, compose the table the way you want it using the Normal template. You may have to move the table to the right so that part of it does not go into the left margin, which will otherwise get clipped unless you reset the left margins (see below) (and you move the table by putting your cursor on the left border of the table until you see the -||- symbol, then pull in the direction you want).  For the table, you can include borders of various colors/thicknesses, and include any type/color of shading offered (real neat!). You can also customize fonts and font attributes used for the table text.

2. Select the table, along with some text outside the table (i.e., a paragraph marker -- this is important for wide tables - don't do a table select!) and do a Copy to the clipboard (found under the Edit menu).

3. Go over to SHED and paste what you just copied (Paste is found under the Edit menu).  You should see what you selected -- what you see is what you get -- if you don't like it, simply go back to WfW and play around til you get it the way you want.  If you are satisfied, in SHED simply do a save to a SHG file, and you've got it!  If you want to add hotspots at that time you can as well, or do it later.

4. In your WinHelp rtf source file, reference the *.shg and compile!

When you view your table in the resulting WinHelp file, and under different video resolutions, you should get the table to look just like the original in WfW (including colors, shading, and borders), and it should remain quite sharp and even-sized across the range of video resolutions (I use VGA, 800x600, and 1024x768 -- I compose my tables in 1024x768 resolution).  It is also quite space saving when compressed into the WinHelp file, taking up a LOT less space than its equivalent compressed bitmap (or bitmaps if MRBC is used), and the WinHelp file is a lot quicker to compile (large bitmaps take forever for the WinHelp compiler to chew on).

At this point in yesterday's post, I lamented the fact I could not get the process to work for tables wider than 6", but I found a way to be able to make arbitrarily wide tables (of course, you have to view these wide tables either in an ordinary jump window, as a popup would clip the table).  What you must do, first of all, is select text outside the table as well as the table itself before copying -- a paragraph marker works fine (why this is so is unknown). In addition, you have to do a Page Setup in WfW, which you bring up by double clicking on the ruler (be sure to have the ruler visible as I haven't found anywhere else you can bring up the Page Setup).  Within Page Setup, go to the Paper Size function and reset the paper size to increase the paper width between the side margins enough to contain the table.  You can do a print preview, found under the file menu in WfW, to see if the page width is wide enough.  During this process, if you see any warning messages saying the print page/margins are not wide enough (or some warning like that), just ignore these messages as you don't plan to print out the table anyway (and you don't have to go into Print Manager, found in the Control Panel, to reset anything regarding page width.)

I would assume the above process would also work for other metafile-like objects created under WfW and other drawing applications.

Happy experimenting!  I'm quite pleased and happy with the results.

Jon Noring
OmniMedia

from a message posted to comp.os.ms-windows.programmer.winhelp (the WinHelp Usenet newsgroup), by Jon Noring; excerpted from Ron Loewy’s integral compilation in WinHelp format (which may be downloaded from Compuserve and ftped from SimTel -- see the Online Sources lexia)


y mtjs essential utilities
Topic Contents

 All you need to do a help file...

 ShgRez

 Paint Shop Pro

 EDI Install Pro


y mtjs general development utilities
Topic Contents

 Go back to the beginning

 WizManager

 Media Center

 Bookshelf

 Clipmate

 Recorder


x data Eschalon Development
Eschalon Development Inc.

24-2979 Panorama Drive

Coquitlam, BCV3E 2W8

Canada

Phone: +1-604-9453198

Fax/BBS: +1-604-9457602

Compuserve: 76625,1320

Internet: 76625.1320@compuserve.com


y nota about
Nota Bene

This help file is intended primarly for users of Lamaura
Development’s authoring tool, SOS Help! Info-Author.
However, since this is freeware and most things
discussed or presented here have the potential to
interest anyone developing help systems, we suppose
there’s no way it will be limited to SOS Help! users. So,
we assumed it and some text is specifically oriented for
these users. We are writing this note lest SOS Help!
based developers find some phrases and concepts
puzzling or out of context (sorry, folks).


x data Cobble Hill Software
Cobble Hill Software

Allen Sim

Cobble Hill Software

395 Henry Street, #3N

Brooklyn, NY 11201

United States of America

Phone: +1-718-8528045

Compuserve: 74551,3060

Cobble Hill Software documents software on paper and electronic formats.


x data Mijenix Corporation
Mijenix Corporation

Mijenix Corporation

6666 Odana Road, Suite 326

Madison, WI 53719

United States of America

Phone/Fax: +1-608-2771971

Compuserve: 74774,564

Internet: 74774.564@compuserve.com

Compuserve forum: GO MIJENIX

Makers of WizManager Pro and a host of useful file management utilities for Windows.


x data Share Warehouse Australia
Share Warehouse Australia

Share Warehouse Australia Pty Ltd.

Suite 32, Level 4, 301 Castlereagh Street

Sydney, NSW 2000

Australia

Phone/Fax: +62-2-2111304

Australian shareware vendor.


x data Der PD-Profi
Der PD-Profi

Der PD-Profi

Gerd Zöttlein

Schulstrasse 13

D-86666 Burgheim

Germany

Phone: +49-8432-1296

Fax: +49-8432-8674

Compuserve: 100326,53

Internet: 100326.53@compuserve.com

German shareware vendor.


x data P. & A. Company
P. & A. Co. Ltd.

P. & A. Co. Ltd.

302 Bellwins, 1367-23

Nakagami, Akishima

Tokyo, 196

Japan

Phone: +81-425-46-9141

Fax: +81-425-46-9142

Japanese shareware distributors


x data Thornton Software Solutions
Thornton Software Solutions

Thornton Software Solutions

PO Box 26263

Rochester, NY 14626

United States of America

Phone: +1-716-2276505

Fax/BBS: +1-716-2271145

Compuserve: 70743,2546

Internet: 70743.2546@compuserve.com

of Clipmate for Windows fame


y nota thanks William
thanks, [image] William.


About the  Hypershelf  Version

ou may unearth any hidden topic from any help file, using the SeqTopicKeys WIN.INI variable, so you have a way to access all the Hypershelf specific topics here. But this and 12 other topics in the file will only really make any sense to users of [image] Hypershelf.

These 13 extra topics provide the hypertext with a structured approach, as opposed to the more web-like nature of the stand-alone version. In the Hypershelf version, information scattered through a number of topics in secondary windows and popups appear organized on common ground basis. Of course, everything is here, so any lexia that would not conform to a valid organisational pattern was dumped in the “Untitled Topics” section, even if it actually had a title.

Speaking of which, you may find the naming of topics intended to appear in popups and secondary windows, a bit strange (and also the Hypershelf specific lexias, of course). You’re right, it is strange...

You should probably add this file to a shelf of WinHelp related electronic books, such as the HAG and others. Hypershelf will magically integrate it in your personal Knowledge Base of WinHelp related matters, in a seamless way.


z hf Template Topics
Template Topics

ook at this topic and compare it with any of the others that were conceived to appear in the main window. It has the same basic structure. For development purposes, you’ll eventually need to define the “look” of your system. Once this is done, if you are a SOS Help! Info-Author user, you may create one “skeleton” or template topic for each situation in the foreseeable future.

It’s then a matter of loading these template topics and saving them under other names (in the wysiwyg SOS Help! authoring environment you work on a topic by topic basis, of course). Bitmaps, segmented hypergraphics, links et al. will get saved. A really neat and useful possibility.

We didn’t delete the template topics we’ve used. They are all collected here.


z hf See Also Topics
See Also Topics

ll the several “See Also” topics (“Related Topics” lists) accessed by use of the floating menu in the stand alone version and the appropriate non-scrolling region symbol/icon in both the Hypershelf and the stand alone versions, follow.


z hf Mid Topic Jump Topics
Mid Topic Jumps Topics

ll the mid topic jumps topics (“Topic Contents” lists) which are accessed either by (1) use of the floating menu in the stand alone version or (2) by the appropriate non-scrolling region’s symbol/icon in both the Hypershelf and the stand alone versions, follow this topic.


z hf A note on the topics collected here
A note on the topics collected here

ypically, this is the “Untitled topics” section of Hypershelf, a dumping ground for lexias whose authors didn't see fit to title, normally because they only serve specific purposes  in specific situations, as popups or secondary windows topics.

In fact, SOS Help! Info-Author makes it obligatory to title any and every topic. Nevertheless, there are scores of them that don't bear any significance outside their immediate framework.

We’ve collected them all (and some more) in this group.


"Glossary How To" Topics
“Glossary How To” Topics

he topics in this group are the “meat” of the project.  They show how to add a “Glossary” feature to any help file and we've even included a basic glossary with some of the most usual “hypertext” related terms. Use of secondary windows is addressed at length and a number of development tricks and devices are discussed.

It is to be hoped that these lexias will assist you in the creation of work that’s more professional and efficient.


z hf Where to Spend Money
Addresses of Providers

ata Window topics galore. (Snail) Mail and e-mail addresses, phone, fax and BBS information of places where people will be most happy to help you get rid of the weight in your pockets.

This is about investment: It’s up to you to regain the weight and add more to it.

We start with the addresses of WinHelp extension providers, followed by some WinHelp developers, world wide web of reputed shareware vendors (support shareware!) and miscellaneous providers.

Most topics include a note explaining the activity of the company, just for the purpose of direct consulting with Hypershelf. Some don’t have this information — we regret, but the fact is, a simple search will in every case uncover further details.


z hf WinHelp Extensions Developers
WinHelp Extensions Developers

hese are places in America, Europe and Australia where you can shop for WinHelp vitamins. A Maylasian addressed was almost included, but the product was too specific, although nice (so, Asia is out). Listed in alphabetical order.


z hf Miscellaneous Providers
Miscellaneous Providers

his group includes providers referred to in the hypertext and for which no particular category was created for the Hypershelf version of the file.


z hf Shareware Vendors
Shareware Vendors

ddresses for the best shareware vendors from around the world. You may buy the shareware versions of software from them, as well as the registered ones. Always remember:

SUPPORT SHAREWARE

if you use it, pay for it!


z hf Lexias of Quotations
Quotation Lexias

mong the many quotations in the document, the ones in this group were selected for their particular relevance and insight. Included, among others, are Prof. George Landow’s remarks on the promise of “Hypertext”, the Code for Communicators of the STC and Jon Noring’s suggestions on how to use the Hot Spot Editor to get Word’s good looking tables into help files in a relatively painless manner.


y a william's buttons
Usual Button Rows

buttons gracefully provided by William Meisheid


y sa complex
Related Topics

 Why a “Glossary”?

 How to make it?

 A typical approach

 A different approach

 Care with details

 Creating a proper “Index”


The Complicated Way - Alternate
A More Complex Approach

o, you are way past needing a Glossary. You are after a Dictionary.  You might consider having one topic for each letter (sorry, we won’t be considering more elaborate alternatives than this), either in a secondary window or in the main window.

In each topic's non scrolling region, you can place a bitmap with the corresponding letter “pressed”, like this:

in Microsoft Bookshelf,
© 1987 - 1992 Microsoft Corporation.

(If you want to go back, use the “Back” button on the toolbar or the  appropriate item on the floating menu) As you can see, the button setup may very well give the impression of an actual pressed button.


y sa how this help file was done
Related Topics

 So, what’s in the trunk?

 WinHelp Development Resources

 About this help file


y mtjs how this help file was done
Topic Contents

 In the embrace of a wysiwyg authoring environment ...

 Defining styles and making templates ...

 Small Touches for WinHelp ...

 The 3d touch in the dialog boxes ...


y nota baggage
Nota Bene

The documentation for the [image] Small Touches for WinHelp dlls
isn't included in the baggage because the package hasn’t
been released yet. We are using a “Work in Progress” version.

If you wish to use its features, please contact [image] SINFIC directly.

Some or all the stuff included here will be out of date by the time
you’re reading this; the best way for you to keep up-to-date is to
access the online resources we mention in the topic on
 Online Sources for WINHELP.EXE.


y mtjs baggage
Topic Contents

 Go back to the beginning

 wh-gly.zip: a ready to use “Glossary” project

 stysheet.zip: this project's style sheet

 source files: this project’s source files

 wh3d.hlp: documentation for Tom Gibson’s dll

 shgrez.zip: ShgRez utility from Stephen Jenkins

 hypershef specific files: for users of Hypershelf


y sa baggage
Related Topics

 How this help file was done

 WinHelp Development Resources

 DLLs and Extensions

 About this help file


Professional Organisations

ou may get counsel and help [image] online, but if you actually find yourself making a living out of producing “help”, you’ll eventually feel the urge for personal contact. You’ll want to meet the people who share your interests and activities, have lively discussions in the pleasure of their presence and learn from the masters of your craft: in short, one day you’ll want to find that you belong. And of course, you are then bound to learn that the fulfillment of that opportunity will help you grow professionally and as a human being. The two organisations mentioned here may serve you well in your search.

STC — Society for Technical Communication

	Created in 1953, it is an American based professional association serving the [image] technical communication profession at large — i.e. writers and editors, graphic artists and technical illustrators, translators, managers and supervisors, educators and students, independent consultants and contractors, photographers and audiovisual specialists, etc. — with a membership of more than 18,000 members in 140 worldwide regional groups. Regular member activities happen mainly in the framework of these regional groups or of the current 13 Professional Interest Committees (PIC). These are groups of members with common experience and interests: “Environmental, Safety, and Health Communication” is one of them; others include “Multimedia”, “Online Information”, “Usability”, “Advanced Technology” or “Quality”. Membership includes subscriptions to a quarterly journal, “Technical Communication” and to “Intercom”, an almost monthly newsletter. There’s also the STC Annual Conference, with a range of educational programmes, seminars and workshops. For American residents, the annual dues are USD 85 (USD 110 for other countries). Contact the [image] STC directly for further information.
WinWriters

 WinWriters is an enterprise of the 3 authors of [image] Developing Online Help for Windows: Scott Bogan, David Farkas and Joe Welinske (president). It publishes a professionally produced quarterly journal (plus disk) on WinHelp and promotes the annual WinHelp Conference, in the winter, in Seattle, WA. You may obtain further information by contacting their office directly.


y sa books
Related Topics

 E-Texts

 Examples and Samples

 Online Sources

 Professional Organisations

 DLLs and Extensions

 More DLLs

 Essential Utilities

 General Development Utilities


y sa whdr
Related Topics

 Books

 E-Texts

 Examples and Samples

 Online Sources

 Professional Organisations

 DLLs and Extensions

 More DLLs

 Essential Utilities

 General Development Utilities


y sa e-texts
Related Topics

 Books

 Examples and Samples

 Online Sources

 Professional Organisations

 DLLs and Extensions

 More DLLs

 Essential Utilities

 General Development Utilities


y sa examples and samples
Related Topics

 Books

 E-Texts

 Online Sources

 Professional Organisations

 DLLs and Extensions

 More DLLs

 Essential Utilities

 General Development Utilities


y sa online sources
Related Topics

 Books

 E-Texts

 Examples and Samples

 Professional Organisations

 DLLs and Extensions

 More DLLs

 Essential Utilities

 General Development Utilities


y sa professional organisations
Related Topics

 Books

 E-Texts

 Examples and Samples

 Online Sources

 DLLs and Extensions

 More DLLs

 Essential Utilities

 General Development Utilities


y sa main dlls
Related Topics

 More DLLs

 Books

 E-Texts

 Examples and Samples

 Online Sources

 Professional Organisations

 Essential Utilities

 General Development Utilities

 The Trunk


y sa essential utilities
Related Topics

 Books

 E-Texts

 Examples and Samples

 Online Sources

 Professional Organisations

 DLLs and Extensions

 More DLLs

 General Development Utilities

 The Trunk


y sa general development utilities
Related Topics

 Books

 E-Texts

 Examples and Samples

 Online Sources

 Professional Organisations

 DLLs and Extensions

 More DLLs

 Essential Utilities


x data WinWriters
WinWriters

WinWriters

3415 SoundView Dr. W

Seattle, WA 98199

United States of America

Phone: +1-206-2852605  • Fax: +1-206-2160322

Compuserve: 71640,3260

WinWriters publishes the quarterly The WinHelp Journal (annual subscriptions start at USD 100) and promote the yearly WinHelp Conference. In case it proves necessary, you may reach David Farkas at farkas@u.washigton.edu and Scott Bogan at 73160,2412 on Compuserve.


x data PC Techniques Bookstream
PC Techniques Bookstream

PC Techniques Bookstream

7721 E. Gray Road, Suite 204

Scottsdale, AZ 85260

United States of America

Phone:+1-602-4830192

Fax: +1-602-4830193

Great Service.


x data Computer Manuals
Computer Manuals

Computer Manuals

50, James Road

Birmingham B11 2BA

United Kingdom

Phone:+44-121-7066000

Fax: +44-121-7063301

Computer Manuals probably has the largest selection of mail order computer books in Europe.


y a landow book
Excerpts from the Landow Book

“In some distant, or not-so-distant, future all individual texts will be electronically linked to one another, thus creating metatexts and metametatexts of a kind only partly imaginable at present.”

“Electronic linking (...) has radical effects upon our experience of author, text, and work, redefining each. Its effects are so basic, so radical, that it reveals that many of our most cherished, most commonplace ideas and attitudes toward literature and literary production turn out to be the result of that particular form of information technology and technology of cultural memory that has provided the settings for them. This technology — that of the printed book and its close relations, which include the typed or printed page — engenders certain notions of authorial property, authorial uniqueness, and a physically isolated text that hypertext makes untenable. The evidence of hypertext, in other words, historicizes many of our most commonplace assumptions, thereby forcing them to descend from the ethereality of abstraction and appear as corollaries to a particular technology rooted in specific times and places.”

citations from Hypertext, a book by George Landow, © 1992 John Hopkins University Press


x data Sageline Publishing
Sageline Publishing

William Meisheid

Sageline Publishing

502 Oella Avenue

Ellicot City, Maryland 21043

United States of America

Phone:+1-410-4651548 • Fax: +1-410-7442456

Compuserve: 70713,2225

Internet: 70713.2225@compuserve.com

Sageline (“information is only as good as its accessibility”) Publishing, where thoughts are still and always in progress, specializes in hypertext products and services.


x data Good Book Guide
The Good Book Guide

The Good Book Guide

24 Seward Street

London EC1V 3GB

United Kingdom

Phone (Orders): +44-171-4909905

Phone (Customer Service): +44-171- 4909900

Fax: +44-171- 4909908

The Good Book Guide dispatches British available books, videos, gifts and other “cultural” items to every country on Earth. An option to it is [image] Europa Books.


y mtjs books
Topic Contents

 Go back to the beginning

 Developing Online Help for Windows

 The Developer’s Guide to WINHELP.EXE

 Hypertext

 Other books


y g context strings
context strings and mid-topic jumps

Any given WinHelp topic has several identifying elements: (a) the topic's name, that'll be used for the “Search”, “Back” and “History” dialogs; (b) the topic’s context number (“value”), used for identification purposes in context-sensitive help; (c) the topic's hash code, which is used by the WinHelp engine; and (d) the topic's context-string (or “identifier”), as defined by the help author during development (when creating any links, these are the identifiers actually used by the help author). The rules for naming context-strings are stricter than the ones used for the titles, but will not be covered here.

In fact, any point of any topic may have its own context-string: all that's neccessary is to add a rtf statement for the effect: #{\footnote # context_string}, where context string is to be replaced by the actual one. You can then use this context string to define jumps not to the beginning of the topic, but to the point in the topic which you marked with it.

This is named a mid-topic jump (or intra-topic jump, as opposed to the inter-topic ones).


y g dlls
dll

Dynamic Link Library. A computer program, normally coded in C or Pascal, that is used to customize or extend WinHelp’s capacity.

The WinHelp engine is conceived in a such a manner as to allow some of its limitations to be overcome by the use of external programming. Desirable features, such as the ability to print all topics of the help file in one go, the ability to detect the user's screen resolution for a more acurate positioning of the help file windows, the ability to use embedded fonts, the ability to run topic macros on topic exit, et cetera — all these nice features and more may be achieved through the use of programs contained in dlls, called up by WinHelp just like any of the genuine (internal) macros.


y g jump
jump

The essence itself of the hypertext experience: a link between two topics designed to change the focus of the reading,  from topic A to topic B.

The creation of jumps, at a par with the definition of search (index) keys, is probably the most important and complex aspect of hypertext authoring. So, it should be left to the reader (just kidding, but in a true to form hypertext environment, the readers definitely should have ways to draw their own paths through “hyperspace”). Since in WinHelp this is not normally possible, the author has a responsability to carefully consider his approach to jumps. The first advice here probably is: don't overdo it. Power is never to be wasted, but to be put to use wisely. Click-happy users will jump to exhaustion if given a chance and in the end will get confused and lost and angry with you. Make jumps if you feel it's absolutely neccessary and actually makes sense. Identify them with words as clearly as you can (use this kind of talk: “You may obtain more details about this subjet by consulting Topic A or B”). Try to have them contained under an umbrella (for instance, “See Also: Topics such and such”).


y g popup
popup

Voilá — one before your respectable eyes!

A link between two topics designed in a way as to allow the focus of the reading to be maintained in the original outbound topic. The inbound topic appears on top of the originator, just until a key is pressed or a mouse click happens. Useful for notes, definitions and clarifications. Similar to a footnote in a book.


y g navigation
navigation

The experience of reading non-sequential material, by following the available paths. In more sophisticated phrasing, the “trail blazing” of hyperspace.


y g pixels
screen resolutions: colours, pixels and more

To fully understand screen resolution, you need to grasp three different concepts. The first is simple: the actual size of your screen, in inches. You'll come to need a screen that has a diagonal screen size of at least 17 inch. The second is also easy: the number of colours, your monitor and the video card inside your computer, can muster. WinHelp is prepared to handle directly 16 colours, but 256 colours is the default assumed by many multimedia applications. If you see these at 16 colours, you'll usually be apalled (so, if you are a help author with a dll that allows 256 or more colours, you must take into consideration your users’ hardware).

Finally, we get to pixels and things get a little tricky. Any “physical” monitor may show several different “virtual” monitors, depending mostly on the computer's video card. This “virtual” setup is defined in pixels: 640x480, 800x600, 1024x768, 1280x1024 are the lower resolutions, these days. The bigger your screen, the more comfortable will be your work at higher resolutions. WinHelp totally avoids this mess by working with absolute co-ordinates of 1024x1024 points, regardless of actual user screen resolution. So, if you do something that looks nice at 640x480, you may be quite sure that it will look awful at higher resolutions. Some authors just assume 800x600 as a minimum requirement for their work. You'll be the judge of your own case.


y g secondary windows
secondary windows

WinHelp allows you to define up to six different windows to show the topics of your help file. The first one is called “main”, the others — the “secondary” ones — are named by you. Among several limitations, secondary windows don't have menus or a toolbar, so they generally need some sprucing up with macros. Only the main window and one secondary window may be shown at any given time.

The judicious use of secondary windows is one of the factors that may contribute to a better help system: for a glossary; or for an index; or for localized information that you want to allow your users to copy or print (but doesn't make any sense cluttering the main window); or for a more interesting table of contents; or for graphical data; or for whatever you feel the need of.

You must always bear in mind that by default, jumps defined in a secondary window will be shown in it and any popups will inherit its background colour. These features are of major relevance in the design of your system.


y g segmented hypergraphics
segmented hypergraphics

Graphics with “hotspots” defined in them, with links to topics, either in the form of jumps or popups. You may also assign a macro or a series of macros to a hotspot. Segmented hypergraphics are created with a program called “Hot Spot Editor”.

Tricks with segmented hypergraphic include: the ability to automatically place the hotspot information into a new bitmap or meta-file; the ability to prevent WinHelp of performing its hated trick of adjusting graphics accordingly to screen resolution; and the ability to include 256 colour graphics in help files without the need of an external dll. The use of lesser known documented and undocumented features of Microsoft’s HotSpot Editor, with some help from outside software in the last two cases, allows all this to happen.


y a print all
Print Menu

 Print Topic

 Print “Glossary How To” Topics

 Print “WinHelp Development Resources” Topics

 Print Data Window Topics

 Print Quotation Topics

 Print Glossary Topics

 Print Popup Topics

 Print Everything

Normally it is not possible to print more than one topic at a time. This WinHelp shortcoming is addressed and solved here thanks to macros from printall.dll, a part of the Small Touches for WinHelp package. If you require more and/or better control over the printing of this or any other help file (namely, the ability not to have page breaks between different topics, ie the ability to print more than one topic per page in a single print job), you’ll need, and should get Hypershelf.


y a simple case
An Illustration of a Simpler Approach


y sa typical
Related Topics

 Why a “Glossary”?

 How to make it?

 A different approach

 A complex approach

 Care with details


y mtjs typical
Topic Contents

 Go back to the beginning

 The usual visual approach


y a typical case
An illustration of a Typical Approach


y mtjs different
Topic Contents

 Go back to the beginning

 Using colours

 Secondary window size


y sa different
Glossaries

 Why a “Glossary”?

 How to make it?

 A typical approach

 A complex approach

 Care with details


Books

f  the reading was intended to be sequential, we'd have started with “books”. As it is, we just put “Books” at the top of the “See Also” lists. It's only fitting. In the provocative words of [image] one of the books mentioned here, “languages which have not been involved with printing, have become dialects or have disappeared. The same could happen to languages that are not (...) transferred to the world of electronic text storage, manipulation and retrieval. (...) Individual texts or entire languages that do not transfer to a new information medium when it becomes culturally dominant will become marginalized, unimportant, virtually invisible.” It's somehow comforting to live in a time when we can still understand the pleasure of turning pages.

Developing Online Help for Windows
by Scott Bogan, David Farkas & Joe Wellinske
SAMS Publishing, 1993; ISBN 0-672-30230-6

A book for the writer of help files, not the programmer, it assumes in its explanations that the reader has access to a word processor capable of generating RTF files. It is very solid on the design issues, and excels in its descriptions of the development process and the project management strategies. The basic, essential text for help authors, it costs USD 40 and can be ordered directly from [image] WinWriters, the authors’ organisation in the United States.

The Developer’s Guide to WINHELP.EXE
by Jim Mischel;edited by Jeff Duntemann
John Wiley & Sons Inc., 1994; ISBN 0-471-30326-7

Subtitled “Harnessing the Windows Help Engine”, this is assumedly for programmers, but will benefit any author. The plunge into the intricacies of RTF is complete and the pages are full of code and examples for people who want to write dlls for WinHelp. The Help Macro Reference section alone, with a trove of useful undocumented WINHELP.EXE features, is worth every cent of the USD 50 cost of the book. It can be ordered from [image] PC Techniques Bookstream, in the United States and possibly from [image] Computer Manuals in the UK.

Hypertext
by George P. Landow
The John Hopkins University Press, 1994; ISBN 0-8018-4281-6

The only real problem with this book, by a professor of English and Art History at Brown University, in the United States, is that it is subtitled “The Convergence of Contemporary Critical Theory and Technology”. Who, in his right mind, would spend 16 dollars on a book with “The Convergence of Contemporary Critical Theory and Technology” written all over its cover? This is, however — and surprisingly — a true pleasure to read. A long essay on true, real hypertext, it’s full of deep, intelligent and provocative thoughts on the profound cultural and social meaning of this emergent technology. If you really like making help files, you may well have a treat here. The book can be ordered from [image] Sageline Publishing in the US and possibly from [image] The Good Book Guide, in the UK.

You may also be interested in other books:

Designing & Writing Online Documentation:
Hypermedia for Self Supporting Products (2nd Edition)
by Wiliam K. Horton
John Wiley & Sons Inc., Oct. 1994; ISBN 0-471-30635-5

(USD 43; the first edition was subtitled “Help Files to Hypertext” and is available in paperback: ISBN 0-471-50772-5)

Indexes: A Chapter from The Chicago Manual of Style (14th Ed.)
by The Chicago Editorial Staff
Chicago University Press, June 1993; ISBN 0-226-10388-9

(USD 6; the book itself costs USD 40: ISBN 0-226-10389-7)

Indexing from A to Z
by Hans Wellisch
H.W. Wilson, 1991; ISBN 0-8242-0807-2 (price: USD 35)

The Society of Text: Hypertext, Hypermedia
& the Social Construction of Information
anthology edited by Edward Barrett
MIT Press, 1991 paperback edition; ISBN 0-262-552161-X

A collection of essays such as Norman Meyrowitz’s “The Missing Link: Why We’re All Doing Hypertext Wrong” and B. Schneiderman’s “Reflections on Authoring, Editing and Managing Hypertext”, which states (a proposal for) the hypertext author’s 10 commandments. Costs USD 20. The hardcover is available for USD 50 (ISBN 0-262-02291-5).

You may try to order any of these  books either from [image] Book Call, in the US or [image] The Good Book Guide, in the UK.


Online Sources

isted here are some places where you can get and offer valuable help, either in the form of advice from/to fellow WinHelp developers or as downloadable material (some of which is referred to in other lexias — call the See Also popup). Of course, in this day and age, it’s assumed as a matter of course that you have a modem and are connected to the online world. At least until Microsoft Online enters the fray, your main general sources should be Compuserve and the Internet. Of course, if you are a user of SOS Help! Info-Author, [image] Lamaura’s BBS is there to serve you diligently.

Compuserve’s WinSDK Forum

This Microsoft run [image] Compuserve forum is likely to prove your best available resource. People that frequent the WinHelp/Tools section of this forum are regular contributors and do help each other, sometimes in outstanding ways. Most of what the humble author of these lines knows about this craft was learned here. Be advised, the service doesn’t come cheap. GO WINSDK will take you to this forum. There’s a library full of relevant software and of course, a very active message exchanging section.

Compuserve’s WUGNET Forum

Another valuable Compuserve forum, this one has a section on Electronic Publications and Training that discusses WinHelp related matters and has an interesting library. GO WUGNET.

Usenet’s WinHelp NewsGroup

COMP.OS.MS-WINDOWS.PROGRAMMER.WINHELP is the full name. It offers the typical Net lively debate (although not at the expert level you can experience on [image] Compuserve) and Pete Davis’ Frequently Asked Questions file.

Bitnet’s WinHelp Mailing List

Mailing lists will keep your e-mail address busy. Some of them may turn out to be hazardous experiments, but the WinHelp’s one is said to be nice. You may subscribe to it by sending an e-mail message to LISTSERV@ADMIN.HUMBERC.ON.CA, with one line of text: SUB WINHLP-L. You should get, in a matter of days or hours, a reply saying that you are in and including a few instructions, namely on how to unsubscribe.

Internet’s FTP Sites

If it isn’t yet,  let’s hope that Clyde Grotophorst’s sysoped ftp site (from the Library Systems Office of Fenwick Library) will rise soon to become Internet’s reference place for WinHelp related files. Clyde is the editor of [image] InfoPop, the premier online text on the Internet, of which he keeps a WinHelp version. The address for this ftp site is GMUTANT.WRLC.ORG (198.91.36.126) and the directories you should explore are:

• /pub/gmutant - software developed by GMUtant Software, including of course InfoPop for Windows

• /pub/pc

• /pub/pc/windows - Windows 3.x software

• /pub/winhelp - files related to developing Windows HLP files

• /incoming - where contributions go

The other typical places for downloading shareware, freeware, public domain and of course, shareware-disguised demoware on the Net are FTP.CICA.INDIANA.EDU, OAK.OAKLAND.EDU (search for SimTel) and WUARCHIVE.WUSTL.EDU. Your beloved WinHelp files will be buried under a mass of thousands of other files — when telneting to download, you’ll need to know exactly what you are looking for. Also, you should explore the mirror sites for these repositories, since they should be much more efficient on account of having less traffic.

There are cheap cd-rom editions of all the software uploaded to any of these sites, which it may be wise to acquire (you must consult on-line for the official releases; [image] Walnut Creek CDROM catalogue provides a regular, independent edition).


WinHelp Files on WinHelp

ooks not withstanding, we are by definition in the realm of electronic documentation: One is entitled to expect that some hands-on documentation on this subject would exist in a “.hlp” file somewhere. And, in fact, there are a few, just like this one. None compares in depth or quality with any of the [image] books reviewed, but the time has come for things to change...

Microsoft’s Help Authoring Guide

The first thing to know is that WinHelp is a member of Microsoft’s Unsupported Tools family. For this reason, the only available documentation on the authoring of help files was for a time an uncompleted paper manual available in electronic format on the Developer Network cds. David DelGreco, from Intuit — a nice company recently acquired by Mr. Gates — spent precious days porting it to “help” format and then got permission to offer it, by uploading the file to Compuserve and the Internet. The book is still not complete of course, but it's by far the best free reference you'll get about this craft.  David’s explanation on how and why he did it is well worth a reading.

In principle, there’s a more recent and complete version of the HAG (but not in WinHelp format, of course) in Microsoft’s Developer Network / Development Library periodic cd-rom, under the title “Windows Help Authoring Guide for Word for Windows 2.0” and in the first volume of Microsoft’s monthly TechNet cd-roms, under “Help Authoring Guide”. The cds also include Microsoft’s Knowledge Base, with a number of articles on WinHelp. The “Developer Network” and the “TechNet” are subscription programs under which Microsoft provides regularly (and exclusively) a number of tools and documentation for developers and technical people. In case you’re interested, we provide the co-ordinates for the company’s [image] European Subscription Centre and its [image] World headquarters, in Washington State’s Puget Sound area (just for completeness, of course; everybody knows this last address).

Pete Davis’ WinHelp FAQ

This is the [image] Internet’s WinHelp newsgroup FAQ file, as compiled by Pete Davis and made into “help” format by Arthur Muller. It includes (noblesse oblige) typical questions and their answers, an essay on colour use, a lexia on using the Viewer v1 dlls to add full text search, sources for undocumented features, presentation of some authoring tools, and more. The text version for it is occasionally posted in the newsgroup. The help file version may be downloaded from (Internet; anonymous ftp) quasar.sba.dal.ca, directory www/hlp.

Ron Loewy’s WINHELP.HLP

Wow! A compilation of any and every “article” ever posted to the Internet’s WinHelp newsgroup, done automatically with Ron Loewy’s NewsDB, a program conceived to make structured and properly cross-referenced hypertext files in WinHelp format from any bundle of text files, like the ones you get if you download forum messages (oops, “newsgroup articles”). We must confess that in this one case, “the whole picture” is too much of a good thing: a quite overwhelming 6MB of help, with a few gems inside to compensate persistent or lucky probers.

If we consider that the hard job of doing this was software performed, the final outcome is surely impressive. This is a useful file. You may download it from a SimTel mirror on the Internet (look for “whnbd.zip” — a 1.7 MB archive at the time of writing this). If you get curious about NewsDB, contact [image] HyperAct.

Ted Kahn’s Help Info

The profuse use of mid-topic keywords in this help file is owed to Ted Kahn’s file. We’ve read about these frequently, but only when we saw it implemented in Help Info did we really grasp the potential. Yes, the books may be better, but an “illustration” is really worth more than a thousand words. Help Info makes for a few good “illustrations” and includes a collection of unusual, independent buttons for use say, in a “Glossary”. All the source code is duly provided.


Good Examples
A Few Good Examples

othing like an example. Sometimes, examples can be frustrating, because we realize we don’t have the resources to achieve the same outcome. Even in these cases, they may be inspirational. We present here some of the best or most useful we’ve seen (this is a small selection: there’s much more good material out there). You are sure to learn and get inspiration from all of these files.

Thomas Lindström’s DiP - The Digital Computer Magazine

“Everybody's Guide To Digital Publishing & Digital Pictures And Other Windows Sweets”, “but it’s more like a book”. Not only is DiP a pleasure to look at, every issue provides information and a hands-on, practical and useful approach to subjects of utmost interest to people developing graphic, multimedia and hypertext material. If you do not download any of the other files here, you shouldn’t pass up DiP.

“Animation made easy”, “3D rendering and modelling” or “image editing software” are treated by covering the practicalities of the use of such packages as Animation Works Interactive, Pixar Typestry or Adobe Photoshop.  Naturally, “help file creation” is a recurrent subject. The tone is coloquial and light, unlike a typical paper based technical book. You may download valuable samples and shareware versions of DiP from Compuserve’s Graphics Support (GO GRAPHSUPPORT) and WinSDK (GO WINSDK) forums and soon from the Internet. Contact the publisher using the information in the accompanying topic with [image] DiP co-ordinates.

DiP’s editor got the idea of using WinHelp as his development platform partly from the WinOnLine Review, an interesting “digizine” with software reviews, sound, simple animations and a few popuped ads that may be downloaded from Compuserve’s Windows Shareware (GO WINSHARE) forum, from some Internet sites and of course, from the [image] Windows OnLine BBS. If shareware appeals to you, [image] ZiffNet’s monthly ZShare, which is professionally produced, shows the know-how of the company that publishes PC Magazine.

Clyde W. Grotophorst’s InfoPop for Windows

“Welcome to InfoPop/Windows...a Windows 3.1 help database for the Internet.  It's not ENCARTA or a full-blown encyclopedia of the Internet, but perhaps we'll get there eventually...” If you are interested in the Internet (of course, you are), get this. It’s freeware, it’s packed with delightful and relevant information and it’s one of the best sources of information on the Net. You may download it from Compuserve’s Internet New Users forum (GO INETFORUM) or from [image] Clyde’s sysoped ftp site on the Net.

Gavin Scott edition of
Internet’s The Jargon File

“This is the Jargon File, a comprehensive compendium of hacker slang illuminating many aspects of hackish tradition, folklore, and humor”. A wonderful dictionary of computer related terms and anedoctage and a paradigm of Internet at its best, from the original contributors to the iluminated soul that turned it into a Windows help file. May be downloaded from Compuserve’s Windows Fun forum (GO WINFUN) and from a number of Internet ftp sites.

ZiffNet Staff’s The David Alsberg Memorial Cookbook

Well, there are more than one cookbook in help format. You may even download Usenet’s one from the Internet. This is a beautiful one and its creation was an act of love: “David Alsberg was a very active member on ZiffNet for CompuServe whose daily messages brought insights and strong opinions into the forums. His missives spanned the spectrum from computers to social issues; he left his mark. He also won ZiffNet's Quote of the Week for ‘The wonderful thing about standards is that there are so many to choose from...’ David was shot and killed in a video store holdup in New York City at the end of December. It is a sad and lonely feeling to see a message waiting and knowing that it will scroll because the person is not there to answer it. He also had no life insurance. He left a 2 1/2-year-old son, Mark, and a wife, Betty.” ZiffNet’s staff contributed recipes for this USD 5 shareware edition to help raising money for Mark’s trust fund. Includes a noteworthy recipe for Brazilian Feijoada from Ziff-Davis COB Eric Hippeau and his wife, Lynne. Unfortunately, we’ve lost track of the current download sites.

Jon Noring’s Online Books

Jon Noring signs his mail with “Hypertext electronic books for Windows 3.1 are available! Current offerings via anonymous ftp: ftp.netcom.com, /pub/Om/OmniMedia/books. E-book publishing service follows NWU recommendations. WWW home page coming very soon!” With a signature like this, what’s left to say? Maybe that NWU stands for the National Writer’s Union and that according to Jon’s persuasive words, the books are “fully hypertexted, aesthetically pleasing, well-designed, and easy to use; some even have full text search capability!”. Aesop’s Fables, John Cleland’s Fanny Hill: Memoirs of a Woman of Pleasure (without illustrations), Mary Shelley’s Frankenstein (much better as a hypertext than as a Kenneth Brannagh movie) or Sir Arthur Conan Doyle’s A Study in Scarlet (Dr. Watson’s first account of his adventures with Mr. Holmes), among other classic and modern texts (including at least one exclusive), are available. Some are free, some are half-free. Jon’s e-mail address is omnimdia@netcom.com in case you have difficulties with the ftp.

Michael Malcolm Andersen’s edition of
Douglas Adams and John Lloyd’s The Meaning of Liff

The source for this unusual dictionary is great: “In Life (and indeed, in Liff), there are many hundreds of common experiences, feelings, situations and even objects which we all know and recognize, but for which no words exist. On the other hand, the world is littered with thousands of spare words which spend their time doing nothing but loafing about on signposts pointing at places. Our job, as we see it, is to get these words down off the signposts and into the mouths of babes and sucklings and so on, where they can start earning their keep in everyday conversation and make a more positive contribution to society.” Michael’s ongoing implementation is a showcase of superior, if discreet and elegant WinHelp fare. It is generally first uploaded to the Windows Fun forum of Compuserve (GO WINFUN). You may also find it on [image] PsL’s Monthly Shareware CD-ROM.

WindowShare’s Catalogue Électronique

 WindowShare is for France what the [image] PsL is for the United States or [image] The Thompson Partnership is for the United Kingdom: a first rate ASP — Association of Shareware Professionals approved vendor that also serves as a shareware registration base for authors around the  world. They speak English (!), have a forum on Compuserve (!!) and a good diskette based “.hlp” French catalogue that deserves attention. Of course, they are also on the Minitel.

Allan Christie’s Computer Hardware Glossary

Simply couldn’t miss this. The archive is named “glossary.zip”, so our isn’t. It's a nice, little freeware help file from Australia, whose definitions may come in handy if you need the terms and don’t feel like reinventing the wheel. You may download it from the [image] ftp site of the Library Systems Office of Fenwick Library.


General Development Utilities

he five Windows applications presented here may not be truly essential, but any one of them will come in handy sometimes or even all of the time. We wholeheartedly offer a few words of praise for each of our personal favourites (just remember that your choice may probably be very different).

Mijenix’s WizManager Pro

An enhancement to “the” File Manager? Aren’t Symantec wares just the ticket? Who uses File Manager anyway? (We do.) The just released new version of Mijenix’s extension to Windows file management facilities includes a powerful zip/unzip utility that’s ideal for integral backups of complex help systems source files. Also included are a file viewer, a file finder, a duplicate detector, etc. Not speaking of the fact that WizManager goes a long way in making File Manager live up to its name. Prices for Mijenix’s WizManager related software start at USD 15 dolars for a single utility like the zip archiving application and go up to USD 40 for the comprehensive WizManager Pro. We like this wonderful shareware program. We’re giving you addresses for orders or further information from the [image] United States, [image] United Kingdom, [image] Australia, [image] France, [image] Germany and [image] Japan.

JASC Media Center

Media Center may not be ImagePals or even the browser in HiJaak, but it does perform in a superior way a few useful tasks: for starters, it catalogues in a practical manner your “multimedia” files; being from the makers of [image] Paint Shop Pro, it can read and show thumbnail versions of BMP, WMF, GIF, PCX, JPG, CDR, CGM, DRW, DXF, GEM, HBL, PIC, WPG, DIB, CLP, CUT, IFF, IMG, JAS, LBM, MAC, MSP, PBM, PCD, PGM, PIC, PPM, PSD, RAS, RLE, TGA, TIF and WPG files (one should ask them to add SHG to the line, no?); a conversion utility is included; audio (WAV and MID) and animation (AVI, FLC/FLI) files will also be detected, presented and played; a slide show can be organized; and there is a lot more to it too, the least of which aren't just the convenient file management features.

There are a few other graphic (and other media) browser/cataloguers around, some of which are more complete, but the truth of the matter is that at USD 39, Media Center prices the lot out of the marketplace for any imaginable WinHelp development need.

Finally, it has to be emphatically stated that to top everything else, this application is made even more rewarding by [image] Allen Sim’s help file, an elegant show of superior craft. You can order it from the [image] United States, the [image] United Kingdom or [image] France.

Microsoft Bookshelf

If you write, you need a good dictionary and a better thesaurus than the one inside your word processor of choice. The ones in Bookshelf are capable and the technology used to produce them is Viewer, a superset of WinHelp, which makes them of interest for WinHelp developers. Bookshelf also includes other reference material, including two collections of quotations. Being from Microsoft, even in Portugal you can get it from any computer store. If for some strange reason you can’t find it, [image] Educorp’s price for it is USD 69.

Chris Thornton’s Clipmate

Clipmate uses the Windows Clipboard to provide a decent buffering function, including a useful ability to save clipboard capturing sessions. This alone makes it a natural to keep macro logs that you can easily pass over to SOS Help! Info-Author general and topic macro introduction dialogs, without having to repeat the same procedures over and over again. The rest of Clipmate features make it one of the best of the hundreds of utilities available to do exactly the same thing. Clipmate is shareware and may be registered through Compuserve. Costs USD 25, may be ordered from the [image] United States or [image] France.

Windows Recorder

People have this tendency to overlook the unassuming Windows Recorder. Nevertheless, the judicious use of the Recorder will give you shortcut keys to virtually any series of systematic keyword or mouse activity within any Windows computer program. So, the assignment of a certain colour or of a certain bitmap, the specific formatting of a certain piece of text, etc. may be made more straightforward. Do yourself the favour of experimenting with it.

(Yes, there are serious batch programs for Windows, like WinBatch; by all means, try them.)


Essential Utilities

ll that’s needed to make a help file is of course the Windows Notepad, some rtf reference and any version of the help compiler. But then, if you want to keep your mental sanity whilst churning out good stuff, you have to consider the use of a more adequate authoring environment and of a number of other more or less related productivity and enhancement tools. The ones collected here are priceless material.

Time/Slice Systems’ ShgRez
by Stephen Jenkins

WinHelp has a way of “adjusting” any bitmap or metafile or segmented hypergraphic to the user’s screen resolution, an effect particularly noted in the case of the “large fonts setup” for resolutions of 800x600 (S-VGA) and above because the feature doesn’t work properly and the graphics get distorted. The official Microsoft solution is the use of something called the mrbc: multi-resolution bitmap compiler. But then, this is a lot of work and doesn’t work with “.shg” files. An alternative has been using any dll that supports embedded windows, specially [image] ShowBMP because it also supports 256 colour segmented hypergraphics. This is probably still your most satisfactory general solution. A compromise may be found in the use of freeware ShgRez, like we do here. Stephen has found a way of disabling the flag on “.shg” files that makes WinHelp perform its adjustment witchcraft, so that it will leave those graphics untouched. You’ll have to process all your bitmaps with the Hot Spot Editor into the “.shg” format, to have it happen to all the graphics, be they genuine segmented hypergraphics or not and this only works with “.shg” files formed from bitmaps, not Windows metafiles, which can prove a hurdle.

A version of ShgRez is in the [image] baggage, in case you want to try it. Search the [image] online sources provided for a possible newer version. We are also including here (“as is”) tips from WinHelp developers on two HotSpot Editor’s undocumented possibilities, one pertaining to a quasi automatic [image] use of proper, elegant table formatting and the other about the inclusion of [image] 256 colour graphics without the need for a specific dll (be warned that some of the talk may seem a bit esoteric — apparently the authoring tool used was Word, spruced up with some macros, a situation which demands a greater degree of understanding of the underlining structure, from the help author).

JASC’s Paint Shop Pro

We may accept that screen capture and graphic files conversion is the name for Inset Systems’ USD 169 HiJaak Pro for Windows, which includes its own browser. If you have HiJaak, you’re well served. But for WinHelp development, you’ll need look no farther than Paint Shop Pro. It effectively captures screens, magically reduces graphic colour information from 16 million to 16 colours, converts between any of several graphic formats, resizes and resamples, and it’s simple to use too!

At least until current v2.0, Paint Shop Pro is true to form, genuine shareware at its most honourable. After a few months of good service performed, conscience has just forced us to remit the USD 69 for the registered version! We got it from [image] WindowShare in France, but you may get it from JASC in the [image] United States or [image] The Tompson Partnership in the UK. Paint Shop Pro doesn’t include a browser/cataloguer, but JASC does offer an awesome USD 39 [image] package for this.

Eschalon Development’s EDI Install Pro
by Robert Salesas

Just above, we talk about great shareware. So, the first thing to be said about EDI Install Pro is that this is the paradigm for shareware-disguised demoware, an inexcusable marketing-oriented use of the word “shareware” that should be condemned and repelled. This noted, EDI (“Eschalon Development Inc.”) Install Pro is a rich, complete and truly professional solution for software installation. The only satisfactory way to distribute Windows software, including obviously electronic document systems, is to offer an easy, automatic and practical installation procedure. You won’t be able to create an acceptable one for yourself, so you’ll have to buy a specialized package.

Maybe the fact that this is from Canada — a country with two languages (for the time being) — helped Robert Salesas realize that all the messages, dialog boxes, etc. should be able to be edited using a resource editor. So, you may easily translate everything to your own language and/or modify extensively the look of  the setup procedure. This is made even more extensive by the possibility of using dlls to extend the product’s already generous line of features.

The only documentation available for EDI Install Pro are the help files, which are good (“yes, we know you can't take it to the bathroom — just think of all the trees we're saving”). There are two versions of the software available: the one that works, is named “Developer” and costs USD 180. It may be acquired from [image] Eschalon Development Inc. in Canada or [image] WindowShare in France.


DLLs and Extensions

hese days, there must exist hundreds of extensions to the basic abilities of WinHelp, thanks to available external programs (.EXE) and dynamic link libraries (.DLL). We review some of them here. Be advised, not only is this far from being an exhaustive list, it is seriously biased (you'll eventually come to have your own list and we regret any shocking absence you may uncover). Speaking of biased, don't forget to check the nice words we have for our own dll package, [image] Small Touches for WinHelp.

In this topic, we’ll cover the best stuff available, none of which (tanstaafl!) comes free.  In another one, we’ll speak about some nice, but less ambitious material, some of which is actually free (tanstaafl?).

The Windows Help engine has proved to be a viable electronic document platform. Developers are “pushing the envelope” basically along 2 distinct ways: multimedia on one side and document and information management on the other. Although WinHelp does have relevant multimedia potential in it, it seems obvious that information management is the “natural”, professionally sensible and most promising path to follow.

Virtual Media Technology’s Hypershelf

Developed in Australia (and exported to the world!), this extension to WinHelp is an end-user product that allows help files scattered around a computer to be organised and seamlessly integrated into logical “bookshelfs”, to be given an hierarchical, interactive table of contents and to be graced with an efficient full text search mechanism (if you are a Hypershelf user, you will want to extract from the [image] baggage the Table of Contents information for this help file). An impressive tour de force, whose first version was a creation of John Bradnam, Hypershelf has other relevant features, such as a unique print engine: You may obtain further information from [image] Australia, the [image] United States or the [image] United Kingdom. (Em Portugal, contactar a [image] SINFIC.)

Hypershelf’s end user suggested price is USD 69. Developers of help systems wishing to add Hypershelf to their collections (and they really should) may obtain a special “publisher’s license”. If you find that the cost of this licensing scheme doesn’t fit your pocket, you may consider a compromise with Jim Mischel’s [image] SearchAll.

HyperAct’s Interactive Help for Windows
by Ron Loewy

To begin with, you’ll be able to have topic or hotspot macros with more than 254 characters. Then, instead of having each topic macro within each topic, you’ll have a simple execute macro in the topic and a text file with all your macros, in Pascal-like fashion, allowing much easier management. Your “IfThen” and “IfThenElse” nested macros will be replaced, if you wish (and you will) by commands and statements that actually make sense and are simple to use and understand. You’ll also have the possibility of asking things from your users and using their replies interactively. And there’s a number of other nifty details, including lots of esoteric features that’ll appeal to “power users”. You may obtain more information about this USD 149 dll directly from [image] HyperAct, in the United States.

Dr. Rudolf Bumm’s ShowBMP

The WinHelp essential multimedia extension, from a surgeon of Munich, Germany. Dr. Rudolf got it absolutely and impressively right! You’ll be able to add video, animations and sound “objects” to your WinHelp projects, thanks to the judicious use of embedded windows. You’ll also be able to include 256 or more coloured bmps, gifs, pcxs and jpeg encoded files, which may be automatically retrieved from baggage during the online session. Then, there’s the feature of the 256 colour end-user-definable segmented hypergraphics... A collection of great dlls for USD 149, downloadable from (and payable to) [image] Compuserve or orderable directly from [image] Dr. Rudolf himself.

Ability Software’s SearchAll
by Jim Mischel

A poor man’s [image] “Hypershelf”, SearchAll (from the author of [image] The Developer’s Guide to WINHELP.EXE) is a Windows Help extension (executable and dll) whose dll you can add to help systems to allow your users a single, integrated keyword index for a set of different files (via the “Search All” dialog). You may also use the executable (plus a help file you’ll have to create) as an end-user tool to single-index any group of help files on your disk. SearchAll is an elegant solution. The package offers the added benefit of providing help through an innovative, controlled “helper” system designed by [image] Mary M. Deaton.  SearchAll costs USD 149 and may be ordered from [image] Ability Software, in the United States.

Yet to be released on the multimedia front, you may want to consider Gen Kiyooka’s Multimedia WinHelp, a USD 200 collection of ambitious multimedia extensions that may be ordered from eminent trademarking experts [image] Blue Sky Software and of course the (almost legendary by now) WinHelp version of Jeff Kovitz’s TouchSend Tools, which are to cost a cool USD 400 but will include a host of dream features. Some of these features, like a [image] scripted macro language or [image] clicklable buttons anywhere have meanwhile been provided, at least partially, by competitors, but the WinHelp TsT are certain to arrive with a bang. You may check its availability directly from [image] TouchSend Management Consulting offices in Tallahassee, Florida.


y sa care
Related Topics

 Why a “Glossary”?

 How to make it?

 A typical approach

 A different approach

 A complex approach

 Small Touches for WinHelp


y a ji
The JumpId Macro

Let's say the context-string is “glossary_mtj2”.

In SHED.EXE, you'd either select the type Jump,
with glossary_mtj2 as the context string or the type
Macro, with JumpId( `' , `glossary_mtj2' ) as the macro.


y mtjs care
Topic Contents

 On using bitmaps

 On windows sizes

 On jumps from topics in secondary windows

 On global glossaries

 Ramblings...


x quote Story of the HAG - Help Authoring Guide
Story of the HAG

(...) I don't hang out in the forum anymore, so I don't know what's going on in the WinHelp world. The HAG is showing its age, but at the time I created it, it was the ONLY alternative to the lousy documentation in the MSC SDK documentation.

Yes, the HAG is available in RTF form as WHAT in the CD-ROM forum (I forget the GO keyword now).  Here's the story of the HAG...

I pestered the people in the SDK forum in late spring of 1992 about the source of the Help Authoring Guide and got the runaround. Apparently the HAG text was from some class or seminar at or related to Microsoft.

Consider that it contains detailed instructions for the Project Editor and the WHAT templates, neither of which are viable retail products.  In fact, they are listed as "unsupported tools" on the Developer's CD-ROM, where they ended up. Because so much of the HAG was devoted to the Project Editor and WHAT, I suspect that they really didn't know what to do with it. So the documentation of those tools, along with a wealth of information that was not fully or clearly explained in the MSC SDK, was made into a MS-Viewer file and put on the CD-ROM.

A colleague told me about the Windows Help Authoring Guide on the CD-ROM and since I was in the midst of trying to figure out how to make a Help file for our first Windows product, I jumped at the knowledge.  It was great, but I didn't have a CD-ROM and ended up making printouts of relevant sections as I needed them.

That became impractical, so I started bugging the sysops in the SDK forum. I found out the source was "owned" by the CD-ROM forum people, and they were very unresponsive to my queries.  Actually, I think they just didn't know anything about the source of the HAG, literally and figuratively.

Since I needed to get a couple of other people up to speed on creating Help files (even as I was learning it!), I did a hackerish thing: I made a Windows recorder macro to copy and paste each screen into it's own little text file. Mind you, the trip through the clipboard removed ALL formatting and symbols. Then I concatenated the 600 or so text files into about twenty files which represented the "chapters" in the original structure.

Now I had several megabytes of text to format...  I created a macro, which I called the Style Bar.  I consisted of a tall, thin window with about 15 buttons on it.  They said "1 Head", "2Head", "Normal", "Bullet 1", "Bullet 2", etc. When you pressed the shortcut key (like 1 for "1head"), the macro formatted the current paragraph, jumped down to the next paragraph, and showed the Style Bar again.  I spent 4 1/2 days SOLID just sitting there going "1-n-b-b-b-n-n-1-2-n-n...."  I thought I'd lose my mind!

It wasn't until much later that I noticed things like if you put the text "{bmcgraphic.bmp}" on a line as an example, HC will interpret it as a command, and the example will be gone.  There are many glitches.

Inventing the table of contents took me a couple more days to get right. All in all I spent 10 solid mind-breaking days turning a bunch of text into the HAG. After a few days of discussion, I got permission from Microsoft to upload the HAG to the SDK forum. About three weeks after that they uploaded WHAG.ZIP, which is the original RTF source to the MS-Viewer version, to the CD-ROM forum.  I reeeallly wish I had that as a starting point.  Quite ironic, really.

I never got the time to redo the HAG.  I wrote some macros to create spreadsheets of the organization of your help file, and another one to parse out all your keywords, sort of like an index.  I made numerous improvements and modifications to the WHAT templates, and of course I wrote some help files for some products.  Now I work in a different area and create help files only for internal documentation...because I can.  <g>

The HAG was my very first help file, and it shows. I uploaded it freely to the SDK forum and the Internet because at the time it was the only really useful source on developing WinHelp files and that seemed more important than the presentation of the information.

David DelGreco

from a message posted to the WinHelp/Tools message section of Compuserve’s WinSDK forum by Patrick J. Winters; June 20, 1994; © 1994 Compuserve Incorporated


y a microsoft unsupported tools
Not quite unsupported, actually

In the case of WinHelp, unsupported for Microsoft means
the availability of really capable authoring stuff, including
the recently released HULK - Help Universal Kit, that pur-
potedly “covers all the common tasks involved in editing,
modifying, testing and building help files”.

If only more software companies would support their
material as Microsoft “unsupports” WinHelp...


x data Microsoft
Microsoft

Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
United States of America

Phone: +1-206-8828080
Fax: +1-206-9367329
Telex: 160520

If you are writing and need a reply in acceptable time, refer very clearly and in big type the broad subject of your inquiry (vg, “TECHNET CD INFORMATION REQUEST” or “DEVELOPER NETWORK INFORMATION REQUEST”).


x data Microsoft European Subscription Centre
Microsoft

Subscription Centre
P.O. Box 5147
2900 EC Capelle a/d IJssel
The Netherlands

Phone: +33-10-2588864
Fax: +33-10-2588863

If you are from a EU/EC country, you’ll be able to pay any subscription in your own currency, with a regular bank cheque from your regular bank; and the service is corteous and efficient.


y mtjs online sources
Topic Contents

 About Online Sources

 Compuserve’s WinSDK forum

 Compuserve’s WUGNET forum

 Usenet’s newsgroup

 Bitnet’s mailing list

 Internet’s anonymous ftp sites


Opening Topic

CNS - Companhia Nacional de Serviços, SA.


x data Compuserve
Compuserve

Compuserve Corporation
5000 Arlington Center Blvd.
P.O. Box 20212
Columbus, Ohio 43220
United States of America

Phone US: +1-614-4578650
Phone UK: +44-117-9760681
Phone Germany: +49-89-66550-0

Compuserve allows no non-sense local phone number access from more countries than any other comparable American based commercial oriented online service.


y a microsoft forums on cis
About Microsoft’s Compuserve forums

The first time you issue a GO command to any of
Microsoft’s online forums, you’ll be requested to fill out a form.


y nota online sources
Internet’s NB

No, we won’t be giving you here the slightest idea about
what the Net is or how to access it. Buy a book on the
subject, buy any of the zillions of magazines out there
with INTERNET spread all over the cover or try to get
your hands on Wally Grotophorst’s [image] InfoPop for Windows.


y mtjs samples and examples
Topic Contents

 Go back to the beginning

 DiP - The Digital Computer Magazine

 InfoPop for Windows

 The Jargon File

 The David Alsberg Memorial Cookbook

 Online books from Omnimedia

 The Meaning of Liff

 Catalogue Électronique

 Computer Hardware Glossary


y a dip
DiP - The Digital Computer Magazine


x data DiP - The Digital Computer Magazine
DiP

DiP - Ängsgården AB
Råsslavägen 160
S-618 32 KOLMÅRDEN
Sweden

Phone/Fax: +46-11-391281
Compuserve: 100435,727
Internet: dip@nordnet.se

DiP will be on the World Wide Web and at a ftp site

(by the way, don’t worry: everything is in English)


x data ZShare
ZiffNet

ZShare, a publication of Ziff-Davis Interactive

ZiffNet Monthly Shareware Review

United States of America

Compuserve: GO ZIFFNET (and search)

ZiffNet is hosted by Compuserve, but runs independently: you’ll have to pay an additional monthly charge to access it from Compuserve. ZShare itself isn’t freeware: it may only be legally obtained by download from ZiffNet forums. To obtain further information, buy any ZD magazine.


x data WinOnLine Review
Windows OnLine

  WinOnLine Review

  WinOnLine Shareware Review

  United States of America

  Phone: +1-510-7364376

  BBS: +1-510-7368343

An American BBS with thousands of scrutinized Windows, MS-DOS and OS/2 shareware, freeware and public domain software. The regular “.hlp” newsletters, with “Cache La Byte” editorials, are as a rule a pleasure to read.


y nota examples
Nota Bene

If the references to Compuserve and the Internet in
this lexia puzzle you, we strongly advise a jump to
the [image] Online Sources topic. Hopefully, you’ll find
some information there to get you started in the
online world.


y a hacker
hacker

 [originally, someone who makes furniture with an axe] n.

1. A person who enjoys exploring the details of programmable systems and how to stretch their capabilities, as opposed to most users, who prefer to learn only the minimum necessary.  2. One who programs enthusiastically (even obsessively) or who enjoys programming rather than just theorizing about programming.  3. A person capable of appreciating hack value.  4. A person who is good at programming quickly.  5. An expert at a particular program, or one who frequently does work using it or on it; as in ‘a UNIX hacker’. (Definitions 1 through 5 are correlated, and people who fit them congregate.)   6. An expert or enthusiast of any kind.  One might be an astronomy hacker, for example.  7. One who enjoys the intellectual challenge of creatively overcoming or circumventing limitations.  8. [deprecated] A malicious meddler who tries to discover sensitive information by poking around.  Hence ‘password hacker’, ‘network hacker’.  The correct term is cracker.

(...)

from The Online Hacker Jargon File, version 2.9.12, 10 May 1993


y a alsberg
Cover illustration of the cookbook


x data PsL - Public (software) Library
PsL

Public (software) Library
P.O. Box 35705
Houston, TX 77235-5705
United States of America

Phone: +1-713-5246394
Fax: +1-713-524-6398

Compuserve: 71355,470

PsL sells the shareware and registered versions of software and runs a very reputable and well established registration service for authors the world over.


x data WindowShare
WindowShare

B.P. 2078

F-57051 METZ cedex 2

France

Phone: +33-87-308557

Fax: +33-87-323775

Compuserve: 100031, 3257

Compuserve forum: GO WSHARE

Minitel: 3615 Boutique LicenseWare


x data Thompson Partnership
The Thompson Partnership

The Thompson Partnership

Lion Buildings, Market Place

Uttoxeter

Staffs ST14 8HZ

United Kingdom

Phone: +44-1889-5664601

Fax: +44-1889-563219

Compuserve: 70007,5560

Internet: sales@ttp.co.uk


x data STC - Society for Technical Communication
STC

Society for Technical Communication

901 N. Stuart St., Suite 904

Arlington, VA 22203-1854

United States of America

Phone: +1-703-5224114

Fax: +1-703-5222075

BBS: +1-703-5223299

Internet: stc@tmn.com

“As a professional society, STC uses its resources to provide you, the technical communicator, with high-quality programs and professional development services.”


x quote STC Code for Communicators
Code for Communicators

As a technical communicator, I am the bridge between those who create ideas and those who use them. Because I recognize that the quality of my services directly affects how well ideas are understood, I am comitted to excellence in performance and the highest standards of ethical behaviour.

I value the worth of the ideas I am transmitting and the cost of developing and communicating those ideas. I also value the time and effort spent by those who read or see or hear my communication.

I therefore recognize my responsability to communicate technical information truthfully, clearly, and economically.

My commitment to professional excellence and ethical behaviour means that I will:

• Use language and visuals with precision;

• Prefer simple, direct expression of ideas;

• Satisfy the audience’s need for information, not my own need for self-expression;

• Hold myself responsible for how well my audience understands my message;

• Respect the work of colleagues, knowing that a communication problem may have more than one solution;

• Strive continually to improve my professional competence;

• Promote a climate that encourages the exercise of professional judgement and that attracts talented individuals to careers in technical communication.

STC - Society for Technical Communication’s Code for Communicators, © STC


y mtjs professional organisations
Topic Contents

 Go back to the beginning

 Society for Technical Communication

 WinWriters


x data Walnut Creek CD-ROM
Walnut Creek CDROM

Walnut Creek CDROM
4041 Pike Lane Suite D
Concord CA 94520-9982
United States of America

Phone: +1-510-6740783 • Fax: +1-510-6740821

Internet, e-mail: orders@cdrom.com

Internet, WWW: http://WWW.cdrom.com

Internet, ftp: fpt.cdrom.com (192.216.191.11)

An interesting cd-rom catalogue (that may be downloaded from the ftp site), including quarterly cd-rom editions of the SimTel and CICA archives (USD 30, USD 20 on subscription).


x data Educorp
Educorp

Educorp

7434 Trade Street

San Diego, CA 92121-2410

United States of America

Phone: +1-619-5369999

Fax: +1-619-5362345

One of the bigger, general interest US cd-rom mail order concerns; naturally, the catalogue is very comprehensive (and includes lots of interesting stuff for multimedia developers); a division of Gazelle Technologies, Inc.


z hf Miscellaneous Topics
Miscellaneous Topics

he following topics are miscellaneous popup topics and others. They round up our “Untitled topics” dumping ground...


z hf WinHelp Developers
WinHelp Developers

ou’ll be creating your own help files, so you probably won’t be needing any of the addresses in this group, except maybe for professional training purposes. They are here for completeness, three from the United States and one from Europe (our own, of course!).


y a SeqTopicKeys
SeqTopicKeys

SeqTopicKeys is a WIN.INI variable.  In the [Windows Help]
section of WIN.INI, if you set SeqTopicKeys=1, then you can
step through the topics in the help file in sequential order by
pressing Ctrl+Shift+RightArrow. Ctrl+Shift+Home takes you
to  the first topic in order.

from a message posted to the WinHelp/Tools message section of
Compuserve’s WinSDK forum by Jim Mischel; October 11, 1994;
© 1994 Compuserve Incorporated


y a Fernando Pessoa
Fernando Pessoa

from a painting by Almada Negreiros


y a source files
Source Files

Actually, the source files for the project aren’t here. Sorry.

Only when we had everything ready to be packed, did we realize
that the source files overall size was over 500 KB! Since we don’t
believe the source will appeal to most readers of this document,
we decided to made it available in a separate archive, which you
should find wherever you got this file from.

In case you don’t find it, contact [image] SINFIC  for more information.

The reference stayed in the topic for completeness.


y a hypershelf specific files
Hypershelf Specific Files

Actually, these files (with the structured table of contents
and full text index info) aren’t here. They’ve been made into
an installation procedure option.

The reference stayed in the topic for completeness.


x orientation Tree


y a Macintosh
Macs are somewhere else

Your computer’s mouse has at least two buttons. Don’t forget to use the one in the right.

Now that we’ve grabbed your attention, please note that most of what amounts to instructions pertaining to using this file can be found in the topic “About This File”. Those, plus the notes in this popup should cover your clarification needs. We regret any features left unexplained.

The Tree button in the toolbar provides a way for you to muster in a glance and jump from a central place to the topics the author considers more relevant. You may also jump to them, under a different perspective, from the "Table of Contents" underneath this popup. And you may also want to consider just using the browse buttons (we’ve implemented one single sequence to make it easier for you).

Don’t forget to check the search feature. If after printing you don’t like the main window’s size, use the “Window” menu option to readjust it.

We hope that you won’t get (very) lost in hyperspace and soon find your ways around the place.


x orientation WinHelp
Electronic Publishing

In a world of lans and the internet, company-wide documents such as procedure manuals, quality assurance specifications or catalogues, cry for availability and distribution in electronic format. Information is retrieved in a snap, thanks to features such as search keys, indexing and full text searching. Structuring and integration of data means easier exploring and productive browsing. Extensive possibilities for using colours allow the production of appealing material. Updating is simple and straightforward. Availability is immediate. Electronic publishing makes sense because it increases a company’s efficiency by saving time.

Among the innumerable authoring platforms available to create electronic documents, the surprising performance of Microsoft Windows’ help engine should be seriously considered. It is a standard, it boasts a large basis of authoring tools and the reader mechanism is freely and readily available on any installation of Windows. Knowledge and professional training on the subject are plentiful, a world-wide developer community exists and the price of the development tools is extremely good value. WinHelp probably makes more sense than any other alternative.


x orientation Portugal
Portugal

Please, note that we wouldn't recommend such a “dark” style sheet (and ensuing look) as the one being used here, in your own projects. In this case, we dared because we are writing specifically to you, a peer in hypertext systems development. We used the chance to explore some possibilities. There aren’t many opportunities for that and the ones that arise shouldn’t go to waste.

Cultures are still different, even in the planet of the Coca-Cola, the MacDonald’s and the Jeans. In Portugal, people still go late in the night to restaurants, to have a meal while enjoying songs of hopeless sadness about death, sorrow and lost loves.

There’s a chappel in Évora, whose walls are covered with human bones. At the entrance, an inscription says something like “We the bones resting here — for yours, we wait”.

Details from a sunny country, with too much history to account for...


y a a softer look
A Softer Look

Try the following:

• 72,0,38 for the non scrolling region (NSR) or a close solid colour

• 255,255,232 for the scrolling region

• dark grey (128,128,128) for the main text

• dark red (128,0,0) for the popup titles

• use light blue (0,255,255) for the NSR buttons, instead of white

• (for disabled state, paint the NSR buttons with dark grey)

• use the default WinHelp popup definitions

• choose an appropriate WinHelp jump definition

Leave the rest more or less as it is and check the suave look&feel.


y a hypershelf books
Illustration of Hypershelf’s File Integration


Lamaura Development Limited


SOS Help! Info-Author


x z authoring team
written by Pedro Leite Fragoso

designed by Bruno Matos Serra

proof read by Rod Stuart

Acknowledgements


Poem - Introduction
Fernando Pessoa

arold Bloom, a conservative professor at Yale and New York universities, has just shared a personal vision of western culture’s literary canon in the 578 pages of his book The Western Canon: The Books and School of the Ages (Harcourt Brace, US). He selects 26 core authors, including Fernando Pessoa.

This stirred the following comment from Time magazine’s literary critic on service: “This grouping, Bloom’s élite among the élite, holds few surprises: an obligatory academic obscurity (Portuguese poet Fernando Pessoa)...”

tss, tss, tss...

 Follows an Álvaro de Campos poem. A light, innocent piece could have been selected. We opted instead for the full “melancholy, mysterious, mildly paranoid, incontestably Portuguese” stuff.


Poem
Tobacconist's (Excerpts)

 am nothing.

Never shall be anything.

Cannot will to be anything.

This apart, I have in me all the dreams of the world.

Windows of my room,

Room of one of the millions in the world about whom nobody knows who he is

(And if they knew who he is, what would they know?),

You give on the mistery of a street constantly trodden by people,

On a street inacessible to all thoughts,

Real, impossibly real, certain, strangerly certain,

With the mystery of the things under the stones and lives,

With death to put damp in the walls and white hair on men,

With Destiny to drive the car of all down the roadway of nothing.

I today, am defeat, as though I knew the truth.

I today, am lucid, as though I were just going to die

And had no longer any connection with things

Except a leave-taking, this house and this side of the street turning into

The line of carriages of a train, and a whistle blown for departure

From inside my head,

And a jolt to my nerves and a creaking of bones at moving off.

I, today, am perplexed, like a man who has thought and found and forgotten.

I, today, am divided between the loyalty I owe

To the Tobacconist's on the other side of the street, as a thing real outside,

And to the sensation that all is dream, as a thing real inside.

I have failed altogether.

As I have not achieved any design, perhaps it was all nothing.

The apprenticeship they gave me —

I've dropped from it out of the window at the back of the house.

I went out into the country with grand designs,

But there I met with only grass and trees,

And when there were people they were just like the rest.

I move from the window, sit down in a chair. What shall I think about?

What do I know of what I shall be, I who don't know what I am?

Be whatever I think? But I think so many things!

And there are so many people thinking of being the same thing of which there cannot be all that many!

Genius? At this moment

A hundred thousand brains are busy dreaming of themselves as geniuses like me,

And history will not mark — who knows? — even one,

And nothing but manure will be left of so many future conquests.

No, I don't believe in me...

All the lunatic asylums have in them patients with many many certainties!

And I, who have no certainty at all, am I more certain or less certain?

No, not even in me...

In how many garrets, and non-garrets, in the world

Are there not at this hour geniuses-in-their-own-eyes dreaming?

How many high and noble and lucid aspirations —

Yes, really and truly high and noble and lucid —

And who knows wheter realizable? —

Will never see the light of the real sun, or reach the ears of people?

The world is for the person who is born to conquer it,

And not for the one who dreams he can conquer it, even if he be right.

I have dreamed more than Napoleon performed.

I have squeezed into a hypothetical breast more loving kindness than Christ,

I have made philosopies in secret that no Kant wrote.

But I am, and perphaps always shall be, the man of the garret,

Even though I don't live there;

I shall always be the one who was not born for that;

I shall always be the one who had qualities;

I shall always be the one who waited for them to open to him the door at the foot of a wall without a door,

And sang the ballad of the Infinite in a hen-coop,

And heard the voice of God in a well with a lid.

Believe in myself? No, and in nothing.

Let Nature pour out over my ardent head

Her sunshine, her rain, the wind that touches my hair,

And the rest that may come if it will, or have to come, or may not.

Heart-diseased slaves of the stars,

We conquer the whole world before getting out of bed,

But we wake up and it is opaque,

We get up and it is alien,

We go out of the house and it is the entire Earth

Plus the Solar System and the Milky Way and the Indefinite.

(...)

Musical essence of my useless verses,

If only I could meet with you as something of my own doing,

Instead of staying always facing the Tobacconist's opposite,

Trampling underfoot consciousness of existing,

Like a carpet that a drunk stumbles over

Or a doormat the gipsies stole and was worth nothing.

But the Lord of the Tobacco Store has come to the door and stopped in the doorway.

I look at him with the unease of a head twisted askew

And the unease of a soul understanding askew.

He will die and I shall die.

He will leave the shop-sign; I shall leave verses.

At a certain stage the shop-sign also will die, and the verses also.

After a certain stage the street where the shop-sign was will die,

And the language the verses were written in.

Later will die the revolving planet on which all this took place.

On other satellites of other systems, something like people

Will continue making things like verses and living under things like shop-signs,

Always one thing opposite another,

Always one thing as useless as another,

Always the impossible as stupid as the real,

Always the underlying mystery as sure as the sleep of the surface mystery,

Always this or always some other thing or neither one thing nor the other.

(...)

Excerpted from Tobacconist's

Álvaro de Campos, 1928

(Pessoa as Campos)

in “Selected Poems • Fernando Pessoa”

(magnificently) translated by Jonathan Griffin

Penguin Books, 1982; ISBN 0-14-042.161-0

 • if available, may possibly be ordered from [image] The Good Book Guide, in the UK or [image] Book Call, in the US


x data Book Call
Book Call

Book Call

59 Elm Street

New Canaan, CT 06840

United States of America

Phone: +1-203-9665470

Fax: +1-203-9664329

The Book Call world service takes orders from any country for any book in print in the United States and have an efficient and corteous service. You may also try the [image] Reader’s Catalog.


Soup
Açorda Alentejana

Dry Soup of Garlic and Fresh Coriander Alentejo-Style
6 servings

Note: absolutely fresh (or frozen) coriander (you'll find it year round at fancy greengroceries and specialty food shops) and good quality olive oil.

4	large garlic cloves, peeled and quartered

2 ½	cups of fresh coriander leaves

(measure loosely packed; lots of this)

2	teaspoons of coarse salt

1/3	cup olive oil

6	medium eggs

7	cups boiling water

6	cups day-old “real” bread, 1½  inch chunks

1/2	teaspoon freshly ground black peper (optional)

Boil the water. Grind the garlic, coriander, and salt to little tiny bits. Transfer to a large heat-proof bowl and blend in the olive oil. Break the eggs, slide into the boiling water, poach 2 minutes; lift to kitchen roll paper to drain; save the cooking water, keeping it at a gentle boil. Add the bread to the bowl, sprinkle with pepper, toss well with the coriander mixture. The bread should stay in chunks. Pour in the saved egg-poaching water (don't care about the bits of egg white) and stir gently to mix. Ease the eggs on top of the soup, distributing them evenly; sprinkle more minced fresh coriander, to your liking (which shouldn't be much, if any, the first time). Serve it, it's ready. This is fast, cheap and good for a light meal: don't forget, an egg for each portion.

You may just boil the eggs and serve them with the soup, one for each person. What was said about the boiling water is still true. Also, it may be served with a piece of boiled dried salt cod per person.


More DLLs

orrowing the words from [image] Developing Online Help for Windows, “Stage 4 is the transition from a rough but functional help system to a fine-tuned and polished piece of work that users will truly appreciate (...) Rough edges are removed, walls are painted, floors are carpeted, and amenities are added.” As “help” files get more refined, you may come to feel the need to add elements of sophistication to your work. The libraries referred to in the other dll lexia are a body of essential, distinguished extension material. The ones mentioned below, for the most part, just allow for nifty, but sometimes striking detail. Use of these will appeal to people who care about the finishing touches.

SINFIC’s Small Touches for WinHelp
by José Humberto Bento

This help system serves as a showcase of [image] some Small Touches’ features. Others include the abilities to use embedded fonts (true type or raster), to show a bitmap for a certain period of time, to run macros synchronously, to present messages in dialog boxes or to get basic (Yes/No) input from users. Small Touches includes two public domain dlls, which come with full source and may be copied at will (winsize2.dll and printall.dll) and a commercial library. WinSize includes a number of functions that detect users’ screen resolutions and colours and allow conditional control of them by the help author and PrintAll provides a flexible and easily applicable Print feature.

Small Touches for WinHelp costs USD 35 and may be ordered directly from [image] SINFIC, in Portugal. The package, including the public domain components, will be made available for download from Compuserve and the Internet.

Ron Burk’s HelpTools

A number of features from [image] Small Touches for WinHelp have their origins in this free, wonderful collection of macros. Ron Burk is the editor of the Windows/DOS Developer’s Journal and he had planned a book titled “WinHelp for Programmers and Technical Writers”, which unfortunately didn't make it to publication (at least, not until now). All isn’t lost however, we've got the Tools. Among the many features, there's a totally flexible print macro; macros that copy (a) the contents of a topic to a text file and (b) files from the baggage to an external file; a macro that allows the caption of windows to be changed at any given moment; or a macro that allows the user to select the default path for file operations.

Tom Gibson’s ThreeD

This public domain dll does one single, simple thing: it converts any WinHelp dialog box into its “ctl3d” equivalent. Tom Gibson has two versions of this small wonder, the one we're using here and another that works with the newer version of Microsoft 3D library. The dll’s documentation is [image] extractable. (By the way, thanks Tom!)

Stefan Olson’s Olson Software Help Tools

If we had been using Stefan Olson’s Help Tools, the fake buttons in the secondary data windows wouldn't have been fake, but real and clickable. We would have been able to have a button toolbar in any secondary window, like Microsoft has in its help file for WinWord 6. We would have been able to easily and efficiently delete the WinHelp menu bar, if we had wished to. And, among other features, we would also haved been able to include 256 colour bitmaps in this or any other help file. And since we’ve already [image] paid 40 US dollars for it, we really should have used it — this help system would have been a better one (but then, we would have needed to make more changes than time allowed). You may download a fully working demo of the package from Compuserve and the Internet.

Ron Pacheco's EWDLL

Here's your chance to include 256 colour bitmaps in help systems for free. The problem is, at the present stage of the dll development the bitmaps won't be able to be read directly from the baggage, so you’ll have to them in the installation directory. EWDLL adheres to the Free Software Foundation conventions: the license agreement occupies a text file with more than 20KB. All the source code is included, of course.


y sa more dlls
Related Topics

 DLLs and Extensions

 Books

 E-Texts

 Examples and Samples

 Online Sources

 Professional Organisations

 Essential Utilities

 General Development Utilities

 The Trunk


x data Europa Books
Europa Books

Europa Books

18 Rudolph Road

Bushey, Watford

Herts WD2  3DY

United Kingdom

Phone: +44-181-9502223

Fax: +44-181-9505015

British based book mail order company.  Another option is the [image] Good Book Guide service.


x data Reader's Catalog
The Reader’s  Catalog

The Reader's Catalog

250  West 57th Street

New York, NY 10107

United States of America

Fax: +1-212-3071973

Internet: readcat@phantom.com

“The bookstore without boundaries”... if they’d only provide a non-800 phone number for international customers. You may prefer to deal  with [image] Book Call.


y a hypershelf
Illustration of Hypershelf’s Table of Contents


x data SINFIC - Sistemas de Informação Industriais e Consultoria
SINFIC

  Sistemas de Informação
  Industriais e Consultoria SA.

Rua dos Soeiros, 311 R/C • P-1500 LISBOA

Portugal

Phone: +351-1-7274132 • Fax: +351-1-7274027

Compuserve: 100447,3652

Internet: 100447.3652@compuserve.com

Developer of [image] Small Touches for WinHelp and Portuguese distributor of the hypertext tools from Lamaura Development and Virtual Media Technology.


x data Softklone UK
Virtual Media / Europe

Softklone UK Ltd.
Preview House, Boundary Rd.
Loudwater, High Wycombe
Bucks HP10 9QT
United Kingdom

Phone: +44-1628-819200
Fax: +44-1628-810314

Compuserve: 70007,4740
Internet: 70007.4740@compuserve.com


x data DEK Software International
DEK Software International

DEK Software International

1843 The Woods II

Cherry Hill, New Jersey 08003

United States of America

Phone: +1-609-4246565

Fax: +1-609-4240785

Compuserve: 75143,3631

Internet: 75143.3631@compuserve.com


x data HyperAct
HyperAct

HyperAct Inc.
P.O. Box 5517
Coralville, IA 52241
United States

Phone/Fax:
 +1-319-3518413

Compuserve: 76350,333
Internet: rloewy@panix.com


x data Dr. Rudolf Bumm
Dr. Rudolf Bumm

Dr. Rudolf Bumm

Sperberstrasse 50a

D-81827 Munchen

Germany

Compuserve: 100025,2206

Internet: 100025.2206@compuserve.com


x data KNOWware
KNOWware

            “Information you can use”

Mary M. Deaton

301 35th Ave S.

Seattle, WA 98144

United States of America

Phone: +1-206-3230701

Compuserve: 74437,273

Internet: marymd@halcyon.com


x data Ability Software
Ability Software

Ability Software

c/o Joe Lucia

1042 Guadaloupe Way

Tempe, AZ 85283

United States of America

Phone: +1-602-4331271

Fax: +1-602-8299290

Compuserve: 72506,3275


x data Blue Sky Software
Blue Sky Software

Blue Sky Software Corporation

7486 La Jolla Blvd., Suite 3

La Jolla, CA 92037

United States of America

Phone: +1-619-4596365

Fax: +1-619-4596366

Compuserve: 73473,3633


x data TouchSend Management Consulting
TouchSend Management Consulting

TouchSend Management Consulting Inc.

1904 Chatsworth Way

Tallahassee, FL 32308

United States of America

Phone: +1-904-6686180

Fax: +1-904-6685352

Compuserve:  73374,2071

The Viewer version of the TouchSend Tools are available and are generally considered an essential add-on to that Microsoft’s multimedia authoring environment (a superset of WinHelp).


x data Olson Software
Olson Software

Stefan Olson

4 Anaru Place

Palmerston North

New Zealand

Phone: +64-6-3591408

Fax: +64-6-3552775

Compuserve: 100352,1315

Internet: stefan@olson.manawatu.gen.nz


y mtjs main dlls
Topic Contents

 About WinHelp extensions

 Hypershelf

 Interactive Help for Windows

 ShowBMP

 Search All

 Multimedia WinHelp and Touch Send Tools


y mtjs more dlls
Topic Contents

 The Finishing Touch

 Small Touches for WinHelp

 Ron Burk’s Help Tools

 ThreeD

 Olson Software Help Tools

 EWDLL


y nota more dlls
Nota Bene

All the dlls referred to are available for download on
Compuserve’s WinSDK or WUGNET forums and/or
on some anonymous ftp sites in the Internet. You may
access information about Online Sources by choosing
the Related Topics popup of this topic.


y mtjs e-texts
Topic Contents

 Go back to the beginning

 HAG: Help Authoring Guide

 WinHelp FAQ

 WINHELP.HLP

 Help Info


y nota e-texts
Nota Bene

Unless otherwise specifically noted, the documentation
referred to in this topic should be available for download
from Compuserve’s WinSDK or WUGNET forums and/or
from some anonymous ftp sites in the Internet. Informa-
tion on [image] Online Sources is available here. Also, plea-
se note that a (not very hard) search will reward you with
more help files on WinHelp production.